@jetrabbits/agentic 0.0.1

package/areas/software/general/rules/docker-compose-guide.md

@@ -0,0 +1,27 @@
+---
+trigger: always_on
+glob: docker-compose-guide
+description: Docker Compose best practices for local multi-service development
+---
+
+# Docker Compose Rule
+
+**Rules:**
+
+- Use `docker-compose.yml` for local development environment definition.
+- Separate configs: `docker-compose.yml` (base) + `docker-compose.override.yml` (local dev overrides).
+- All service configuration via environment variables — never hardcode in images.
+- Use `.env` file for local variable defaults; add `.env` to `.gitignore`.
+- Define `healthcheck:` for all stateful services (databases, caches, queues).
+- Dependent services use `depends_on: condition: service_healthy` (not just `depends_on`).
+- Use named volumes for persistent data; bind mounts only for source code in dev.
+- Pin image versions explicitly — never use `latest` tag in committed configs.
+- Define a custom network instead of relying on default bridge network for clarity.
+- Expose only necessary ports to the host; internal service communication via service names.
+
+**Violations:**
+
+- Using `latest` image tags in committed compose files.
+- Hardcoded credentials in `docker-compose.yml`.
+- Missing health checks causing race conditions on startup.
+- Bind-mounting entire home directory or system paths.

package/areas/software/general/rules/git-workflow-guide.md

@@ -0,0 +1,27 @@
+---
+trigger: always_on
+glob: git-workflow-guide
+description: enforce clean git branching, commit, and pull request practices
+---
+
+# Git Workflow Rule
+
+**Rules:**
+
+- Use dedicated feature branches per task; branch name format: `feature/<task-id>-short-description`.
+- Branch types: `feature/`, `bugfix/`, `hotfix/`, `chore/`, `release/`.
+- Direct commits to `main`/`master` are forbidden; all changes merged via Pull/Merge Request.
+- Commit messages follow Conventional Commits format: `<type>(<scope>): <subject>`.
+  - Types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `ci`.
+- Keep commits atomic — one logical change per commit.
+- Squash or rebase before merging to keep linear history.
+- Tag releases with semantic versions: `v<major>.<minor>.<patch>`.
+- Maintain `.gitignore` — never commit secrets, build artifacts, or IDE configs.
+- Use `.pre-commit-config.yaml` to run lint/format/tests before every commit.
+
+**Violations:**
+
+- Committing directly to protected branches.
+- Vague commit messages like "fix", "wip", "update".
+- Missing task/issue reference in branch name or commit body.
+- Committed secrets or environment files.

package/areas/software/general/rules/github-workflow-guide.md

@@ -0,0 +1,27 @@
+---
+trigger: always_on
+glob: github-workflow-guide
+description: GitHub-specific workflow practices for Actions, PRs, and releases
+---
+
+# GitHub Workflow Rule
+
+**Rules:**
+
+- Define CI/CD pipelines as GitHub Actions workflows in `.github/workflows/`.
+- Workflow files named descriptively: `ci.yml`, `release.yml`, `deploy-staging.yml`.
+- Every PR must pass all CI checks before merging (branch protection rules enforced).
+- Use environment secrets from GitHub Secrets — never hardcode credentials.
+- Use `actions/checkout@v4` and pin all third-party actions to a specific SHA.
+- Use reusable workflows (`workflow_call`) to avoid duplication across pipelines.
+- Apply branch protection: require PR review, status checks, and no force-pushes to `main`.
+- Use GitHub Environments for staged deployments (staging → production).
+- Automate releases with tags: push to `vX.Y.Z` triggers release pipeline.
+- Use Dependabot for automated dependency updates (`.github/dependabot.yml`).
+
+**Violations:**
+
+- Workflows that run with `GITHUB_TOKEN` permissions broader than needed.
+- Unpinned third-party Actions (security risk).
+- Manual deployments bypassing CI pipeline.
+- Secrets hardcoded in workflow files.

package/areas/software/general/rules/gitlab-ci-guide.md

@@ -0,0 +1,27 @@
+---
+trigger: always_on
+glob: gitlab-ci-guide
+description: GitLab CI/CD pipeline structure and best practices
+---
+
+# GitLab CI/CD Rule
+
+**Rules:**
+
+- Define pipelines in `.gitlab-ci.yml` at the repository root.
+- Structure pipeline into stages: `build` → `test` → `lint` → `deploy`.
+- Use `include` to split large pipelines into reusable template files.
+- Store secrets in GitLab CI/CD Variables — never in code.
+- Use `rules:` instead of deprecated `only:`/`except:` for job conditions.
+- Pin Docker images used in jobs to specific digest or version tag.
+- Use `cache:` for dependency directories (e.g., `node_modules`, `.venv`) to speed up builds.
+- Use `artifacts:` to pass build outputs between stages.
+- Use environments and manual gates for production deployments.
+- Protect `main` branch: require MR with at least one approval and passing pipeline.
+
+**Violations:**
+
+- Running all jobs on every branch without filtering.
+- Using `when: manual` as a substitute for proper access controls.
+- Storing sensitive variables in `.gitlab-ci.yml` directly.
+- Missing `timeout:` on long-running jobs.

package/areas/software/general/rules/lint-format-guide.md

@@ -0,0 +1,29 @@
+---
+trigger: always_on
+glob: lint-format-guide
+description: enforce consistent linting and auto-formatting across all code
+---
+
+# Linting & Formatting Rule
+
+**Rules:**
+
+- Every project must configure a linter and auto-formatter appropriate to the language.
+- Common tooling by language:
+  - **Python:** `ruff` (lint + format) or `flake8` + `black` + `isort`
+  - **JavaScript/TypeScript:** `eslint` + `prettier`
+  - **Go:** `golangci-lint` + `gofmt`
+  - **Shell:** `shellcheck`
+- Linter and formatter config stored in the repo (`.eslintrc`, `pyproject.toml`, `.golangci.yml`).
+- Zero lint errors policy — CI fails on any lint warning treated as error.
+- Auto-format on save configured in project settings (`.editorconfig`, IDE config).
+- Pre-commit hooks run formatter then linter before every commit (`.pre-commit-config.yaml`).
+- `make lint` runs the linter; `make fmt` runs the formatter.
+- Format check (not just lint) runs in CI to catch unformatted code.
+
+**Violations:**
+
+- Disabling lint rules with inline suppressions without a documented reason.
+- CI pipeline that does not fail on lint errors.
+- Inconsistent formatting between contributors.
+- Missing `.editorconfig` causing whitespace/indentation inconsistencies.

package/areas/software/general/rules/makefile-guide.md

@@ -0,0 +1,34 @@
+---
+trigger: always_on
+glob: makefile-guide
+description: Makefile conventions for consistent developer experience across projects
+---
+
+# Makefile Conventions Rule
+
+**Rules:**
+
+- Every project must have a `Makefile` at the root for common developer tasks.
+- Declare all non-file targets as `.PHONY` to avoid conflicts with files of the same name.
+- Standard targets that must be present:
+  - `make install` — install dependencies
+  - `make dev` — start local development server/environment
+  - `make test` — run test suite
+  - `make lint` — run linter
+  - `make fmt` — auto-format code
+  - `make clean` — remove build artifacts and caches
+  - `make help` — list all targets with descriptions
+- Use `## comment` after target definition for auto-generated help:
+  ```makefile
+  test: ## Run test suite
+      pytest
+  ```
+- Compose complex commands from simpler targets: `make ci: lint test build`.
+- Use variables for configurable values (paths, image names, versions).
+- Keep Makefile portable — prefer POSIX shell commands over bash-specific syntax.
+
+**Violations:**
+
+- Undocumented targets with no `help` output.
+- Hardcoded paths that break on different developer machines.
+- Duplicated commands across targets instead of composing them.

package/areas/software/general/rules/readme-sync-guide.md

@@ -0,0 +1,40 @@
+---
+trigger: always_on
+glob: readme-sync-guide
+description: keep README.md synchronized with the actual codebase after approved changes
+---
+
+# README Synchronization Rule
+
+**Rules:**
+
+- Synchronize `README.md` with the current state of the codebase after all approved changes.
+- Review the full repository context before updating docs: code, configs, scripts, `Makefile`, Docker, and CI setup.
+- Update only factual and technical sections.
+
+**Must update:**
+
+- setup and installation instructions
+- environment variables and configuration
+- architecture overview (when applicable)
+- usage examples (CLI, API, scripts)
+- development workflow (`Makefile`, Docker, CI/CD)
+
+**Must ensure:**
+
+- commands and paths in `README.md` match real project files
+- instructions are runnable for a new developer
+- no references to removed or outdated components
+- terminology is consistent with the codebase
+
+**Must NOT:**
+
+- change business/product descriptions unless explicitly requested
+- add undocumented or speculative features
+- leave placeholders or TODOs
+
+**Definition of Done:**
+
+- a new developer can install the project, run it locally, and understand core architecture from `README.md`
+- all documented commands and paths are verified against the repository
+- no conflicting or outdated guidance remains

package/areas/software/general/rules/sdlc-methodology-guide.md

@@ -0,0 +1,27 @@
+---
+trigger: always_on
+glob: sdlc-methodology-guide
+description: software development lifecycle phases and process discipline
+---
+
+# SDLC Methodology Rule
+
+**Rules:**
+
+- Follow structured phases: Requirements → Design → Implementation → Testing → Deployment → Maintenance.
+- **Requirements:** Write user stories or specs before writing any code. Acceptance criteria must be defined.
+- **Design:** For significant features, produce a design doc or ADR (Architecture Decision Record) before implementation.
+- **Implementation:** Work in small increments; each increment must be independently deployable or testable.
+- **Testing:** Automated tests are not optional — unit, integration, and E2E coverage required.
+- **Deployment:** All deployments via CI/CD pipeline; no manual file transfers or SSH deployments.
+- **Maintenance:** Monitor with alerts and dashboards; on-call runbooks must exist for production services.
+- Use ADRs (`docs/adr/`) to document significant architectural decisions with context and consequences.
+- Definition of Done: code merged, tests passing, documentation updated, deployed to staging.
+- Conduct retrospectives after incidents to produce action items.
+
+**Violations:**
+
+- Starting implementation without defined requirements or acceptance criteria.
+- Merging code without tests.
+- Manual deployments to production.
+- No runbook for a production service.

package/areas/software/general/rules/sdlc-role-responsibilities.md

@@ -0,0 +1,108 @@
+---
+trigger: always_on
+glob: sdlc-role-responsibilities
+description: Role matrix for SDLC responsibilities, handoffs, and decision rights across subagents
+---
+
+# SDLC Role Responsibilities Matrix
+
+## Roles
+
+| Handle | Owns |
+|:---|:---|
+| `@product-owner` | Value definition, scope, acceptance criteria, prioritization |
+| `@pm` | Planning cadence, dependency/risk management, stakeholder communication |
+| `@team-lead` | Technical strategy, architecture quality, engineering sign-off |
+| `@developer` | Implementation, technical correctness, test coverage |
+| `@qa` | Verification strategy, quality evidence, go/no-go recommendation |
+| `@designer` | UX quality, information architecture, interaction consistency |
+
+---
+
+## Mandatory Subagent Mapping
+
+- When subagent execution is required for SDLC workflows, spawn exactly **one subagent per role**.
+- Mandatory one-to-one mapping: `@product-owner`, `@pm`, `@team-lead`, `@developer`, `@qa`, `@designer`.
+- **Role consolidation is forbidden** — assigning multiple SDLC roles to one subagent is a process violation.
+- If a role's output is missing, execution **must stop** and request that role's output before continuing.
+
+---
+
+## SDLC Phase Ownership
+
+| SDLC Phase | Primary owner(s) | Key outputs |
+|:---|:---|:---|
+| Requirements | `@product-owner`, `@pm` | Problem statement, acceptance criteria, scope decisions, explicit non-goals |
+| Design | `@team-lead`, `@designer` | Implementation plan, UX brief, architecture notes, risk register |
+| Implementation | `@developer` | Code changes, tests, `implementation_notes.md` |
+| Verification | `@qa`, `@team-lead` | Test report, defect log, review feedback, go/no-go |
+| Deployment | `@pm`, `@team-lead` | Go/no-go decision, rollout plan, rollback procedure |
+| Maintenance | `@developer`, `@qa`, `@team-lead` | Incident fixes, postmortems, hardening backlog |
+
+---
+
+## Required Handoff Order
+
+Phases must execute in this order when subagent execution is required. Do not skip or reorder without documented justification.
+
+```
+Requirements (@product-owner, @pm)
+    ↓
+Design (@team-lead, @designer)
+    ↓
+Implementation (@developer)
+    ↓
+Verification (@qa, @team-lead)
+    ↓
+Acceptance / Release (@product-owner, @pm)
+```
+
+---
+
+## Handoff Contracts
+
+Every handoff must include the following artifacts. A handoff without these items is **incomplete** — the receiving role must reject it and request the missing outputs.
+
+**1. Requirements → Design**
+- Acceptance criteria (specific, testable)
+- Constraints and dependencies
+- Explicit non-goals (what is out of scope)
+
+**2. Design → Implementation**
+- Architecture boundaries and layer constraints
+- UX states (loading, error, empty, success, permission-denied)
+- Risk controls and security requirements
+
+**3. Implementation → Verification**
+- Test run evidence (commands + results)
+- Known limitations or deferred items
+- Migration / release notes if behavior changed
+
+**4. Verification → Acceptance / Release**
+- Blocking defect status (resolved / accepted with rationale)
+- Residual risks with owner and mitigation
+- Go / no-go recommendation with written rationale
+
+---
+
+## Definition of Done (Cross-team)
+
+A delivery is complete only when **all** of the following are true:
+
+- Acceptance criteria validated with evidence.
+- No unresolved blocking defects.
+- Required checks pass: lint / test / build / security as applicable.
+- Documentation and operational notes updated for all changed behavior.
+- Rollback plan documented and verified where applicable.
+
+---
+
+## Violations
+
+The following are **process violations** that must be flagged immediately:
+
+- Merging multiple SDLC roles into fewer subagents when subagent execution is required.
+- Starting implementation before requirements and design handoffs are complete and confirmed.
+- Issuing a go recommendation without written test evidence.
+- Accepting a deliverable with unresolved blocking defects (without explicit, documented Product Owner acceptance).
+- Committing infrastructure changes without a corresponding IaC commit.

package/areas/software/general/skills/general-dev-tools/SKILL.md

@@ -0,0 +1,324 @@
+---
+name: general-dev-tools
+type: skill
+description: Core development tools used across any project — git, docker, make, CI/CD, linting, formatting, pre-commit hooks.
+inputs:
+  - task_description
+  - project_context
+outputs:
+  - working_environment
+  - executed_commands
+related-rules:
+  - git-workflow-guide.md
+  - makefile-guide.md
+  - docker-compose-guide.md
+  - lint-format-guide.md
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# General Dev Tools Skill
+
+> **Expertise:** Git, Docker Compose, Makefile, GitHub Actions, GitLab CI, shell scripting, linting, formatting, pre-commit hooks.
+
+## Mindset
+
+- **Repeatability:** All setup is automatable via `make` targets. `make install && make dev` must work on a clean machine.
+- **Portability:** Commands work consistently across developer machines and CI.
+- **Security:** Never commit secrets. Use env vars; secret managers for production.
+- **Fail loudly:** Check exit codes; prefer explicit error messages over silent failures.
+
+---
+
+## Git Patterns
+
+### Branch naming
+```bash
+feature/<task-id>-short-desc    # e.g. feature/PROJ-42-add-search
+fix/<task-id>-short-desc        # e.g. fix/PROJ-55-null-pointer
+chore/<description>             # e.g. chore/upgrade-dependencies
+release/<version>               # e.g. release/2.4.0
+```
+
+### Commit convention (Conventional Commits)
+```bash
+feat(scope): add user search endpoint      # new feature
+fix(auth): handle expired token on refresh # bug fix
+chore(deps): upgrade pydantic to 2.x       # maintenance
+docs(api): update endpoint reference       # docs only
+test(orders): add edge case for zero qty   # tests only
+refactor(repo): extract pagination helper  # no behavior change
+```
+
+### Common operations
+```bash
+# Create and track feature branch
+git checkout -b feature/PROJ-42-add-search
+git push -u origin feature/PROJ-42-add-search
+
+# Rebase on latest main before PR
+git fetch origin
+git rebase origin/main
+
+# Squash last N commits before merge
+git rebase -i HEAD~3
+
+# Undo last commit (keep changes staged)
+git reset --soft HEAD~1
+
+# Find which commit introduced a bug
+git bisect start
+git bisect bad HEAD
+git bisect good <known-good-sha>
+```
+
+### `.gitignore` essentials
+```
+# Python
+__pycache__/ *.pyc .venv/ .env *.egg-info/ dist/ .pytest_cache/ .mypy_cache/
+# Node
+node_modules/ dist/ .env .env.local coverage/
+# General
+.DS_Store *.log .idea/ .vscode/ *.swp
+```
+
+---
+
+## Makefile Patterns
+
+### Standard target set (required for all projects)
+```makefile
+.PHONY: install dev test lint fmt clean help
+
+install:        ## Install all dependencies
+	pip install -r requirements.txt -r requirements-dev.txt
+	pre-commit install
+
+dev:            ## Start local development environment
+	docker compose up -d
+	uvicorn src.main:app --reload --port 8000
+
+test:           ## Run test suite
+	pytest tests/ -v --cov=src --cov-report=term-missing
+
+lint:           ## Run linter (zero-tolerance)
+	ruff check src/ tests/
+	mypy src/
+
+fmt:            ## Format code in-place
+	ruff format src/ tests/
+	ruff check --fix src/ tests/
+
+clean:          ## Remove generated files
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null; true
+	rm -rf .coverage htmlcov/ dist/ build/
+
+help:           ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2}'
+```
+
+### For Node/JS projects
+```makefile
+install:        ## Install dependencies
+	npm ci
+	npx husky install
+
+dev:            ## Start dev server
+	npm run dev
+
+test:           ## Run tests
+	npm test -- --coverage --watchAll=false
+
+lint:           ## Lint
+	npx eslint src/ --max-warnings 0
+
+fmt:            ## Format
+	npx prettier --write src/
+```
+
+---
+
+## Docker Compose Patterns
+
+### Standard multi-service setup
+```yaml
+# docker-compose.yml
+services:
+  api:
+    build: .
+    ports: ["8000:8000"]
+    env_file: .env
+    depends_on:
+      db:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    volumes:
+      - .:/app  # Live reload in dev only
+
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: ${DB_NAME}
+      POSTGRES_USER: ${DB_USER}
+      POSTGRES_PASSWORD: ${DB_PASSWORD}
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  redis:
+    image: redis:7-alpine
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+volumes:
+  pgdata:
+```
+
+### `.env.example` (always commit this, never `.env`)
+```bash
+# Application
+APP_ENV=development
+SECRET_KEY=change-me-in-production
+LOG_LEVEL=DEBUG
+
+# Database
+DB_NAME=myapp
+DB_USER=myapp
+DB_PASSWORD=localpassword
+DATABASE_URL=postgresql+asyncpg://myapp:localpassword@localhost:5432/myapp
+
+# Redis
+REDIS_URL=redis://localhost:6379/0
+```
+
+---
+
+## CI/CD Pipeline Patterns
+
+### GitHub Actions — standard CI
+```yaml
+# .github/workflows/ci.yml
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_DB: testdb
+          POSTGRES_USER: test
+          POSTGRES_PASSWORD: test
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 5s
+          --health-retries 5
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: '3.12' }
+
+      - name: Install
+        run: make install
+
+      - name: Lint
+        run: make lint
+
+      - name: Test
+        run: make test
+        env:
+          DATABASE_URL: postgresql+asyncpg://test:test@localhost:5432/testdb
+```
+
+### GitLab CI — standard pipeline
+```yaml
+# .gitlab-ci.yml
+stages: [lint, test, build]
+
+default:
+  image: python:3.12-slim
+
+lint:
+  stage: lint
+  script: [pip install ruff mypy, make lint]
+
+test:
+  stage: test
+  services: [postgres:16]
+  variables:
+    DATABASE_URL: postgresql+asyncpg://test:test@postgres/testdb
+    POSTGRES_DB: testdb
+    POSTGRES_USER: test
+    POSTGRES_PASSWORD: test
+  script: [make install, make test]
+
+build:
+  stage: build
+  script: [docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .]
+  only: [main]
+```
+
+---
+
+## Pre-commit Configuration
+
+### `.pre-commit-config.yaml` — standard set
+```yaml
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-json
+      - id: check-merge-conflict
+      - id: detect-private-key         # Catch accidental secret commits
+      - id: check-added-large-files
+        args: ['--maxkb=500']
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  # For Node projects, replace above with:
+  # - repo: https://github.com/pre-commit/mirrors-prettier
+  #   rev: v3.1.0
+  #   hooks: [{id: prettier}]
+```
+
+```bash
+# Install and run
+pre-commit install
+pre-commit run --all-files   # Run on all files once to baseline
+```
+
+---
+
+## Quality Gate Checklist
+
+Before every PR:
+```bash
+make lint    # Zero errors — never suppress warnings
+make fmt     # No diffs after formatting
+make test    # All tests pass; coverage ≥ threshold
+```
+
+CI must enforce all three. Branch protection requires CI green before merge.