agent-workflow-kit-cli 1.0.0-mvp → 1.2.0

package/dist/core/renderer.js

@@ -6,6 +6,10 @@ import handlebars from "handlebars";
 import { promises as fs } from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
+// Register custom Handlebars helpers
+handlebars.registerHelper("eq", function (a, b) {
+    return a === b;
+});
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 // The templates directory is located at '../../templates' relative to 'dist/core/renderer.js'
@@ -22,12 +26,18 @@ export async function renderTemplate(templatePath, context) {
     return compiled(context);
 }
 /**
- * Reads a static rules file as-is without Handlebars interpolation.
+ * Reads a static template file (rules or skills) with optional Handlebars interpolation.
  * @param filePath Relative path inside templates folder (e.g. 'spring-boot/rules/java-style.md')
+ * @param context Optional key-value data for compilation
  */
-export async function readStaticTemplateFile(filePath) {
+export async function readStaticTemplateFile(filePath, context) {
     const fullPath = path.join(TEMPLATES_DIR, filePath);
-    return fs.readFile(fullPath, "utf8");
+    const fileContent = await fs.readFile(fullPath, "utf8");
+    if (context) {
+        const compiled = handlebars.compile(fileContent);
+        return compiled(context);
+    }
+    return fileContent;
 }
 /**
  * Gets all rules files for a stack.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-workflow-kit-cli",
-  "version": "1.0.0-mvp",
+  "version": "1.2.0",
   "description": "AI-Ready Repository Workflow Generator & Guideline Optimizer for Codex and Antigravity",
   "type": "module",
   "main": "./dist/index.js",

package/templates/common/AGENTS.md.hbs

@@ -1,44 +1,39 @@
 # Repository Agent Guidelines
 
-This repository implements the `agent-workflow-kit-cli` configuration standards for AI coding agents.
+This repository implements the `agent-workflow-kit-cli` standards.
 
 ---
 
-## 🚀 AI Agent Step-by-Step Execution Workflow
-
-AI agents MUST follow this strict 5-step workflow for any task:
+## 🚀 AI Agent 5-Step Execution Workflow
 
 ### 1. 🔍 Step 1: Research & Context Analysis
-- Read existing codebase files relating to the task first.
-- Understand local naming patterns, directory boundaries, and dependency versions.
-- Do NOT make any code modifications or run build commands in this step.
+- **Selective Config Scan:** Read `AGENTS.md`. Only read rule files in `.agents/rules/` relevant to the files/stack you are modifying (e.g. `react-style.md` when editing JS/TS). Do not scan irrelevant rules or skills.
+- **codebase Scan:** Read relevant codebase files, configurations, and `README.md` to understand context and project goals.
+- Do NOT modify code or run build commands in this step.
 
 ### 2. 📝 Step 2: Formulate Implementation Plan
-- Document your proposed design approach.
+- Document your proposed approach.
 - List all files to be created (`[NEW]`), modified (`[MODIFY]`), or deleted (`[DELETE]`).
 - Identify all verification commands to run.
-- Wait for user feedback or proceed intentionally based on user preferences.
 
-### 3. 💻 Step 3: Implementation & Clean Coding
-- Implement changes following strict type safety standards.
-- Conform strictly to the folder structures and layers defined in the Stack Pack section below.
-- Preserve existing comments, docstrings, and licensing headers.
+### 3. 💻 Step 3: Implementation
+- Follow type safety, project conventions, and architecture.
+- Preserve existing comments, docstrings, and license headers.
 
 ### 4. 🧪 Step 4: Verification & Conformance Testing
-- Always run automated verification commands of the detected stack pack (e.g. compile, lint, test, build).
-- If tests or builds fail, fix the errors and rerun until compile/tests are 100% clean.
+- Run automated verification commands (compile, lint, test, build). Rerun until 100% clean.
 
-### 5. 🔍 Step 5: Self-Review & Quality Assurance
-- Review your diff/changes carefully to check for syntax errors, leftover console logs, or redundant imports.
-- Summarize what was changed, what was tested, and confirm that all steps are complete before marking the task as done.
+### 5. 🔍 Step 5: Self-Review & QA
+- Review the diff for syntax, logs, and unused imports.
+- Summarize changes and verification results before finishing.
 
 ---
 
 ## ⚙️ General Engineering Conventions
 - Follow existing patterns in naming, architecture, and layouts.
-- Read files carefully before proposing code updates.
-- Ensure type safety and run clean lint/verify steps before declaring a task as done.
+- Ensure type safety and run verification checks before declaring a task done.
 
 <!-- AWK-START: STACK_PACK -->
 {{{stackContent}}}
 <!-- AWK-END: STACK_PACK -->
+

package/templates/common/skills/build-skill/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: build-skill
+description: Dynamically generates or updates a project-specific skill workflow in the .agents/skills/ directory
+---
+
+Follow this workflow when the user requests to build or bootstrap a new custom skill for this codebase (e.g. `/build-skill medical-report-analysis`).
+
+Inputs:
+- newSkillName: Name of the skill to create (in kebab-case, e.g. `medical-analysis`)
+- skillGoal: Description of the goal or target domain of the skill
+- customSteps: Any specific instructions or steps requested by the user
+
+Steps:
+1. **Analyze Project Context:**
+   - Scan the codebase and read existing `.agents` files to understand local directory layouts, naming conventions, and testing commands.
+
+2. **Formulate the Skill Structure:**
+   - Define a step-by-step workflow that guides an AI agent through accomplishing the target goal.
+   - Separate concerns: Keep the skill focused on execution workflow steps. If there are style constraints or hyperparameters, place them in a separate rule under `.agents/rules/<rule-name>.md` and reference it inside the skill via `@rules/<rule-name>.md`.
+   - Keep the skill file under 8,000 characters to prevent context overload.
+
+3. **Write the Skill File:**
+   - Create the target folder `.agents/skills/{{newSkillName}}/` if it does not exist.
+   - Write the `SKILL.md` file using standard YAML frontmatter:
+     ```markdown
+     ---
+     name: {{newSkillName}}
+     description: {{skillGoal}}
+     ---
+     
+     [Workflow steps and instructions in English...]
+     ```
+
+4. **Verify and Inform the User:**
+   - Print a success message confirming the skill was written.
+   - Advise the user to run:
+     - `npx agent-workflow-kit-cli sync` (to ensure guidelines are synchronized)
+     - `npx agent-workflow-kit-cli export antigravity` (to export and register the new skill with the AI agent)

package/templates/fastapi/rules/python-style.md

@@ -1,22 +1,17 @@
 # Python Code Style Rules
 
-All python code in this project must conform to the following formatting and styling requirements:
-- Use PEP 8 conventions.
-- Format all files with Ruff.
-- Imports must be sorted using Ruff or isort.
-- Use explicit type annotations everywhere.
+- Follow PEP 8. Format & sort imports with Ruff.
+- Require explicit type annotations everywhere.
 
 ## Naming
-- Variables, functions, modules, and API helper functions must use `snake_case`.
-- Classes, exceptions, and Pydantic schemas must use `PascalCase`.
-- Pydantic schemas for incoming writes must use intent suffixes:
-  - `UserCreate` for create payloads.
-  - `UserUpdate` for partial or full update payloads.
-  - `UserRead` or `UserResponse` for response payloads, following the local convention.
-- Repository and service functions should describe actions with verbs, for example `get_user`, `list_users`, `create_user`, `update_user`, and `delete_user`.
+- Variables, functions, modules: `snake_case`.
+- Classes, exceptions, Pydantic schemas: `PascalCase`.
+- Write schemas suffixes: `UserCreate` (creation), `UserUpdate` (updates).
+- Response schemas: `UserRead` or `UserResponse`.
+- Actions: Verb prefix (`get_user`, `create_user`).
 
-## API Endpoint Naming
-- Route path segments must be lowercase nouns, singular or plural according to the existing local convention: `/users`, `/user-profiles`, `/orders/{order_id}`.
-- Do not encode actions in REST resource paths when an HTTP method already expresses the action.
-- Path parameters must use `snake_case`, for example `{user_id}`.
-- Router variables should be named `router`; shared dependency functions should use clear `snake_case` names.
+## API Endpoints
+- Paths: Lowercase nouns (`/users`, `/user-profiles`, `/orders/{order_id}`).
+- Avoid verbs in REST paths (use HTTP methods instead).
+- Path parameters: `snake_case` (e.g. `{user_id}`).
+- Routers: Name variables `router`.

package/templates/python-ai/AGENTS.md.hbs

@@ -0,0 +1,36 @@
+## 🐍 Python AI & Hardware-Integrated Guidelines
+
+### 🔄 End-to-End Agent Development Lifecycle
+AI Agents must execute all tasks following this structured 5-stage lifecycle:
+1. **Design & Code**: Implement pipeline, model, or agent code according to the modular directories below. Keep components stateless and thread-safe.
+2. **Comprehensive Testing**: Write unit tests to check input/output array shapes, verify parameter validation, and mock external API/LLM calls.
+3. **Troubleshooting & Debugging**: When diagnosing errors (like CUDA OOM or camera blockages), load and follow the `@ai-debug` skill workflow.
+4. **Code Quality & Review**: Perform a thorough self-review against `@ai-style.md` (for reproducibility, memory bounds, and prompt segregation). If working on video/hardware integrations, also conform strictly to `@ai-hardware.md`.
+5. **Edge & Production Optimization**: Verify weights quantization, thread safety, and resource cleanups before shipping model scripts.
+
+### 🏗️ Architecture & Directory Conventions
+Organize AI, data preprocessing, and model code in a modular package layout:
+
+```text
+src/
+  data/          # Dataset processing pipelines (cleaning, tokenization)
+  models/        # Model architectures (PyTorch, TensorFlow wrappers)
+  agents/        # LLM workflows, prompts, and agent tools registry
+  training/      # Training and fine-tuning routines
+  inference/     # Inference pipelines or API deployment logic
+notebooks/       # Jupyter/IPython notebooks for EDA and experiments
+configs/         # YAML/JSON configurations for hyperparameters
+```
+
+### ⚙️ Coding Guidelines
+- **Reproducibility**: Set random seeds globally using the helper in `@ai-style.md` for any code creating data splits or training networks.
+- **Resource Management**: Release camera streams (`cv2.VideoCapture`) or serial port interfaces inside `finally` blocks or using context managers.
+- **Thread Safety**: Process high-frequency video frames or sensor inputs on a separate thread; exchange frames using thread-safe queues.
+
+### 🧪 Verification & Linting Pipeline
+Before completing any task, run the following verification commands in the project directory:
+
+```bash
+{{runCommand}} ruff check .
+{{runCommand}} -m pytest
+```

package/templates/python-ai/rules/ai-hardware.md

@@ -0,0 +1,36 @@
+# Python Hardware-Integrated & Edge AI Rules
+
+## 1. Thread-safe Frame & Sensor Capture
+- Do not process camera/sensor input on the main thread. Use a dedicated daemon thread and pass data/frames using a thread-safe Queue:
+  ```python
+  class FrameReader:
+      def __init__(self, source=0):
+          self.cap = cv2.VideoCapture(source)
+          self.queue = Queue(maxsize=10)
+          self.stopped = False
+      def start(self):
+          threading.Thread(target=self.update, daemon=True).start()
+      def update(self):
+          while not self.stopped:
+              ret, frame = self.cap.read()
+              if ret and not self.queue.full():
+                  self.queue.put(frame)
+  ```
+
+## 2. Resource Management
+- Always release camera captures, serial ports, and windows in a `finally` block:
+  ```python
+  try: ...
+  finally:
+      cap.release()
+      cv2.destroyAllWindows()
+  ```
+
+## 3. Frame Buffers
+- Use circular buffers to store frame history to avoid memory leaks:
+  `frame_buffer = deque(maxlen=30)`
+
+## 4. Edge Optimization
+- Avoid pixel loops. Use vectorized NumPy operations (e.g. `binary = (gray > th).astype(np.uint8) * 255`).
+- Quantize model weights to FP16 or INT8 (using ONNX Runtime / TFLite) for CPU/edge deployment.
+

package/templates/python-ai/rules/ai-style.md

@@ -0,0 +1,30 @@
+# Python AI & LLM Style Rules
+
+## 1. GPU & Memory Management
+- Allocate device dynamically (never hardcode `"cuda"` or `"cpu"`):
+  `device = torch.device("cuda" if torch.cuda.is_available() else "cpu")`
+- Wrap evaluation/inference in `with torch.no_grad():` to save VRAM.
+- Clear cache in long loops/batch runs: `torch.cuda.empty_cache()`.
+
+## 2. Reproducibility
+- Set seeds globally at startup:
+  ```python
+  def set_seed(seed=42):
+      random.seed(seed)
+      np.random.seed(seed)
+      torch.manual_seed(seed)
+      if torch.cuda.is_available():
+          torch.cuda.manual_seed_all(seed)
+  ```
+
+## 3. Data Leakage
+- Fit encoders/scalers/tokenizers ONLY on the training split (never val/test).
+- Assert data shapes/bounds before starting training loops.
+
+## 4. LLM & Prompts
+- Decouple prompts: Store prompts in separate files (JSON, YAML, .txt) instead of hardcoding strings in Python files.
+- Validate inputs using Pydantic before calling LLM APIs.
+
+## 5. Metrics Logging
+- Log metrics via standard python `logging` or tools (MLflow, W&B, TensorBoard). Avoid `print` statements.
+

package/templates/python-ai/skills/ai-agent/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: ai-agent
+description: Generates or extends an LLM agent workflow or prompt configuration
+---
+
+Follow this workflow to build a new LLM agent, tool registry, or prompt context loop.
+
+Inputs:
+- agentName: Name of the agent component (e.g., `doc_summarizer`)
+- llmClient: Target LLM model/API (e.g., `openai`, `gemini`, `ollama`)
+
+Steps:
+1. Examine existing LLM adapters, configuration settings, and prompts in the codebase.
+2. Define the system prompt templates:
+   - Save prompts as configuration files (JSON/YAML) or static templates. Do not hardcode long string templates in raw python files.
+3. Implement the Agent client/runner class:
+   - Set up API keys dynamically from environment variables (no hardcoded secrets).
+   - Implement tool registrations (e.g. function calling definitions) with strict parameter validations.
+   - Enforce memory state preservation (e.g., session handling, conversation buffers).
+4. Add unit and integration tests:
+   - Mock API client calls to avoid charging external keys during test runs.
+   - Verify tool parameter validation errors return correct user warning boundaries.
+5. Run validations:
+   - Run tests and quality verification commands.

package/templates/python-ai/skills/ai-debug/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: ai-debug
+description: Systematically diagnoses and resolves Python AI, memory, and hardware errors
+---
+
+Follow this workflow to debug, reproduce, and resolve errors in the Python AI project.
+
+Inputs:
+- errorMessage: Stack trace, error logs, or problem description
+- componentName: Name of the suspected class, package, or API endpoint
+
+Steps:
+1. **Analyze Stack Traces & Exceptions:**
+   - Locate the exact exception class (e.g. `RuntimeError: CUDA out of memory`, `cv2.error`, `ValidationError` in Pydantic).
+   - Find the exact file and line number where the failure occurs.
+
+2. **Diagnose Common AI & Hardware Failures:**
+   - **CUDA OOM**: Check if batch size is too large or if gradients are accumulating (verify if `with torch.no_grad():` is used for inference). Clear cache with `torch.cuda.empty_cache()`.
+   - **OpenCV/Serial blockages**: Check if cameras or ports were left open. Verify resources are closed in a `finally` block or using a context manager.
+   - **Prompt Drift / LLM mismatch**: Validate if the arguments sent to the LLM client match the expected Pydantic schema.
+
+3. **Write a Reproducing Test:**
+   - Before writing the fix, add a minimal unit test under `tests/` that passes the failing input parameters and triggers the exact error.
+   - Run the test and confirm it fails.
+
+4. **Apply the Fix & Verify:**
+   - Fix the bug in the code.
+   - Run the reproducing test and confirm it passes.
+   - Run linter and tests:
+     - `{{runCommand}} ruff check .`
+     - `{{runCommand}} -m pytest`

package/templates/python-ai/skills/ai-model/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: ai-model
+description: Generates or extends a Python machine learning model architecture or training script
+---
+
+Follow this workflow to define a new model architecture or write a training/evaluation routine.
+
+Inputs:
+- modelName: Name of the model component (e.g., `face_encoder`)
+- framework: The target framework (e.g., `pytorch`, `onnx`)
+
+Steps:
+1. Examine existing models or wrappers in the codebase to keep signatures and abstractions consistent.
+2. Define the model architecture class:
+   - Make device configuration dynamic (`device` GPU/CPU delegation).
+   - Use correct data types (e.g. FP32 for training, FP16/INT8 for edge inference).
+3. Write the training or inference execution script:
+   - Set random seeds globally using standard random/numpy/torch configurations.
+   - For training loops: output logging metrics (loss, evaluation score) to TensorBoard/MLflow.
+   - For inference loops: wrap logic within `torch.no_grad()` contexts to save VRAM.
+4. Write tests:
+   - Assert input/output tensor dimensions.
+   - Verify the forward pass with mock inputs (assert shape and type).
+5. Run validations:
+   - Run unit tests and style linter commands.

package/templates/python-ai/skills/ai-pipeline/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: ai-pipeline
+description: Generates or extends a Python data preprocessing or ingestion pipeline
+---
+
+Follow this workflow to create a new dataset pipeline, loader, or feature cleaning routine.
+
+Inputs:
+- pipelineName: Name of the data pipeline component (e.g., `face_alignment`)
+- inputSource: Description of raw input (e.g., `camera_frames`, `text_corpus`)
+
+Steps:
+1. Inspect neighboring codebase files to understand local directory layouts and input/output schema conventions.
+2. Define input preprocessing utilities:
+   - Handle invalid/null inputs, empty values, or dimension mismatches.
+   - Vectorize array transformations using NumPy (avoid pixel-by-pixel loops).
+3. Create the data ingestion/loader class:
+   - Implement batch loading or caching to prevent memory blockages.
+   - For file-based operations, verify try-except-finally release locks.
+4. Add verification and test scripts:
+   - Write a unit test asserting shape transformations, boundary inputs, and types.
+   - Validate execution speed on standard sample frames or test inputs.
+5. Run code formatting:
+   - Run linter/formatter check: e.g. `ruff check .` or `black --check .`

package/templates/react-ts/rules/react-style.md

@@ -1,34 +1,29 @@
 # React + TypeScript Style Rules
 
-All React + TypeScript code in this project must follow these rules.
-
 ## Naming
-- Components use PascalCase and live in PascalCase files: `Navbar.tsx`, `InstallSection.tsx`.
-- Custom hooks use camelCase, start with `use`, and live in matching files: `useAuth.ts`, `useBillingData.ts`.
-- Helper functions and variables use camelCase: `formatCurrency`, `isSubmitting`.
-- Interfaces and type aliases use PascalCase: `ButtonProps`, `AuthState`.
-- Constants that represent fixed configuration may use SCREAMING_SNAKE_CASE only when already established locally.
+- Components: PascalCase (`Navbar.tsx`, `InstallSection.tsx`).
+- Custom hooks: camelCase starting with `use` (`useAuth.ts`).
+- Helpers & variables: camelCase (`formatCurrency`).
+- Types & interfaces: PascalCase (`ButtonProps`).
 
 ## Imports
-- Use absolute imports from the `@/` alias for source modules.
-- Do not use parent-chain relative imports such as `../../components/Button`.
-- Prefer `import type` for type-only imports.
-- Keep feature internals private unless exported through a feature `index.ts`.
+- Use `@/` absolute alias paths. Avoid relative parent paths (`../../`).
+- Use `import type` for types.
+- Keep feature internals private; expose via `index.ts` only when needed.
 
-## React and JSX
-- Keep components focused on rendering and composition.
-- Move data fetching, subscriptions, timers, storage access, and other side effects into custom hooks.
-- Boolean JSX attributes must use shorthand: `<Input disabled />`, not `<Input disabled={true} />`.
-- Pass event handlers as named functions when the body is more than a single expression.
-- Render loading, error, empty, and success states for async UI.
+## React & JSX
+- Components must focus on UI/composition.
+- Move side effects (fetching, subscriptions, timers) to custom hooks.
+- Use shorthand for boolean props: `<Input disabled />`.
+- Handle async UI states: loading, error, empty, success.
 
 ## State Management
-- Prefer local state for component-only interactions.
-- Use Context API for stable app-level concerns such as auth, theme, locale, or configuration.
-- Use Zustand for shared mutable state that changes often or is consumed across distant features.
-- Do not introduce global state for data that can remain feature-local.
+- Prefer local component state.
+- Use Context API for stable app-level state (auth, theme).
+- Use Zustand for frequent, cross-feature state updates.
 
 ## Testing
-- Test user-visible behavior with React Testing Library.
-- Add hook tests when a custom hook owns branching logic, async behavior, or cleanup.
-- Avoid snapshots unless the output is intentionally stable and small.
+- Test user behavior via React Testing Library.
+- Test hooks with complex branching/cleanup.
+- Avoid snapshot testing unless output is small & stable.
+

package/templates/spring-boot/AGENTS.md.hbs

@@ -1,10 +1,19 @@
 ## ☕ Java Spring Boot Guidelines
 
+### 🔄 End-to-End Agent Development Lifecycle
+AI Agents must execute all Java Spring Boot tasks following this structured 5-stage lifecycle:
+1. **Design & Code:** Implement layers following the structure guidelines below. Keep logic inside the Service layer.
+2. **Comprehensive Testing:** Write unit tests for services, `@WebMvcTest` for controllers (covering null inputs, bad payloads, and validation boundaries), and `@DataJpaTest` for database operations.
+3. **Troubleshooting & Debugging:** When debugging failures, load and follow the `@spring-debug` skill to isolate issues and write reproducing tests.
+4. **Code Quality & Review:** Perform self-review using `@code-review.md` to check transaction boundaries (`@Transactional`), exceptions, and security checkpoints.
+5. **Production Readiness:** Verify deployment safety rules in `@production-ready.md` (including database migrations, profiles, and Actuator metrics configuration).
+
 ### 🏗️ Architecture & Package Conventions
+{{#if (eq packageLayout "feature-first")}}
 Follow a strict **feature-first** modular packaging layout. Each feature module (e.g. `customer`) must encapsulate all its layers within it:
 
 ```text
-src/main/java/com/acme/app/
+src/main/java/{{packagePath}}/
   customer/
     dto/
       CreateCustomerRequest.java
@@ -24,7 +33,7 @@ src/main/java/com/acme/app/
 
 Corresponding test directories must match the feature layout exactly:
 ```text
-src/test/java/com/acme/app/
+src/test/java/{{packagePath}}/
   customer/
     repository/
       CustomerRepositoryTest.java  # Custom query repository slice tests
@@ -33,10 +42,42 @@ src/test/java/com/acme/app/
     web/
       CustomerControllerTest.java  # Web MVC slice tests
 ```
+{{else}}
+Follow a standard **layer-first** packaging layout:
+
+```text
+src/main/java/{{packagePath}}/
+  controller/
+    CustomerController.java
+  service/
+    CustomerService.java
+    impl/CustomerServiceImpl.java
+  repository/
+    CustomerRepository.java
+  entity/
+    Customer.java
+  dto/
+    CreateCustomerRequest.java
+    CustomerResponse.java
+  mapper/
+    CustomerMapper.java
+```
+
+Corresponding test directories must match the layer layout exactly:
+```text
+src/test/java/{{packagePath}}/
+  controller/
+    CustomerControllerTest.java  # Web MVC slice tests
+  service/
+    CustomerServiceTest.java     # Business logic unit tests (using Mockito)
+  repository/
+    CustomerRepositoryTest.java  # Custom query repository slice tests
+```
+{{/if}}
 
 ### ⚙️ Coding Guidelines
 - **Dependency Injection:** Prefer constructor injection. Do NOT use field-based injection (`@Autowired`).
-- **DTO Validation:** Request DTOs must enforce schemas using `jakarta.validation.constraints` annotations (e.g., `@NotNull`, `@NotBlank`, `@Size`, `@Email`).
+- **DTO Validation:** Request DTOs must enforce schemas using `{{validationLibrary}}.constraints` annotations (e.g., `@NotNull`, `@NotBlank`, `@Size`, `@Email`).
 - **Layer Separation:** Keep controllers thin; delegate all business rules, transactions, and transformations to the service layer.
 
 ### 🛠️ Tooling & Quality Standards
@@ -61,7 +102,7 @@ The project runs Checkstyle for static analysis and Spotless for code formatting
 </plugin>
 ```
 
-### 🧪 Testing Guidelines
+### 🧪 Testing Guidelines (using {{testFramework}})
 All edits must pass local verification tests before completion:
 
 | Test Type | Requirement | Done Criteria |
@@ -71,9 +112,22 @@ All edits must pass local verification tests before completion:
 | **`@DataJpaTest`** | For custom repository queries | Verify custom query logic and entity-database column mappings. |
 | **`@SpringBootTest`** | Complex integrations only | Smoke test the application startup and critical cross-module integrations. |
 
+{{#if isMicroservice}}
+### 🌐 Microservice Guidelines
+This module is configured as a **microservice** registered under:
+- **Service Name:** `{{springApplicationName}}`
+- **Server Port:** `{{serverPort}}`
+
+**Key Directives:**
+- **Communication:** Always use `@FeignClient` calling service names for communicating with other services. Do not hardcode service ports or URLs.
+- **Resilience:** Protect external requests with Resilience4j circuit breakers and define fallback procedures.
+- **Tracing:** Propagate `X-Correlation-Id` headers and verify trace tracing IDs exist in the logger config.
+- **Exception handling:** Define standard Feign `ErrorDecoder` implementations to map downstream client exception status codes correctly.
+{{/if}}
+
 ### 🚀 Verification Commands
 Before completing a task, run the following verification pipeline locally:
 ```bash
-./mvnw clean test
-./mvnw verify
+{{buildCommand}} clean test
+{{buildCommand}} {{buildVerifyArgs}}
 ```

package/templates/spring-boot/rules/code-review.md

@@ -0,0 +1,22 @@
+# Java Spring Boot Code Review & Security Rules
+
+## 1. `@Transactional`
+- Use `readOnly = true` for read-only service methods.
+- Avoid self-invocation (calling `@Transactional` from same bean).
+- Use `rollbackFor = Exception.class` for checked exceptions.
+
+## 2. Exception Handling
+- Never catch & swallow exceptions. Log with stack trace: `logger.error("Msg: {}", err.getMessage(), err)`.
+- Use `@RestControllerAdvice` for global error mapping.
+- Map custom exceptions (e.g. `ResourceNotFoundException`) to HTTP statuses.
+
+## 3. Security Checkpoints
+- Avoid SQL injection: Use parameterized queries/bind variables, never string concatenation.
+- Enforce authorization via Spring Security annotations (e.g., `@PreAuthorize`) on Controller/Service.
+- Annotate request bodies with validation constraints (`@NotBlank`, `@Size`).
+
+## 4. Quality & Resource Management
+- Prevent resource leaks: Use `try-with-resources`.
+- Keep beans stateless/thread-safe.
+- Remove unused imports, comments, and debug logs.
+

package/templates/spring-boot/rules/java-style.md

@@ -1,14 +1,9 @@
 # Java Spring Boot Style Constraints
 
-Enforce strict coding style and layer definitions in this repository.
+- Style: Google Java style.
+- Imports: standard java first, third-party second, internal last.
+- Generics: Do not use raw types. Specify generic parameters.
+- Architecture: Follow layers in @AGENTS.md.
+- Testing: Cover custom database queries with `@DataJpaTest`.
+- Verification: Run `{{buildCommand}} {{buildVerifyArgs}}` before completion.
 
-## Coding Style
-- Follow standard project style guidelines (default Google Java style).
-- Organize imports cleanly: standard java libraries first, third-party libraries second, internal imports last.
-- Do not use raw types. Always specify generic parameters.
-
-## Integration & Layers
-- Follow rules defined in @AGENTS.md.
-- Ensure all custom database queries are covered by repository slice tests (`@DataJpaTest`).
-- Before completing work, execute:
-  - `./mvnw verify`

package/templates/spring-boot/rules/microservice-style.md

@@ -0,0 +1,22 @@
+# Spring Boot Microservice Design Rules
+
+- Service Name: `{{springApplicationName}}`
+- Local Port: `{{serverPort}}`
+
+## 1. Naming & Ports
+- `spring.application.name` must match the module directory name in kebab-case.
+- Local server ports must be allocated in advance to prevent clashes.
+
+## 2. Inter-service Communication (Feign Client)
+- Do not use hardcoded URLs/IPs. Use Service Discovery (Eureka/Consul).
+- Place `@FeignClient` interfaces in `{{basePackage}}.client` or `{{basePackage}}.feign`.
+- Implement a custom `ErrorDecoder` to propagate downstream HTTP status codes instead of throwing generic 500 FeignExceptions.
+
+## 3. Resilience
+- Wrap outgoing Feign calls in Resilience4j `@CircuitBreaker` or `@TimeLimiter`.
+- Implement a `fallbackMethod` for graceful fallback handling when services fail.
+
+## 4. Distributed Tracing
+- Log actions with `X-Correlation-Id` or `TraceId` (Micrometer Tracing).
+- Configure a Feign `RequestInterceptor` to forward the `X-Correlation-Id` header to downstream calls.
+

package/templates/spring-boot/rules/production-ready.md

@@ -0,0 +1,20 @@
+# Java Spring Boot Production Readiness Rules
+
+## 1. Database Migrations
+- Set `spring.jpa.hibernate.ddl-auto` to `none` or `validate` in production (never `update`/`create`).
+- Manage schema changes using versioned migration files (e.g. Flyway `.sql` scripts in `src/main/resources/db/migration/`).
+
+## 2. Configuration & Profiles
+- Separate environments using profiles (`application-dev.yml`, `application-prod.yml`).
+- Never hardcode credentials. Inject via environment variables: `password: ${DATABASE_PASSWORD:default_dev_pass}`.
+- Use `@ConfigurationProperties` + `@Validated` to check configurations at startup.
+
+## 3. Monitoring (Spring Boot Actuator)
+- Enable Actuator. Configure `/actuator/health` to check database/critical services.
+- Secure sensitive endpoints. Publicly expose only safe ones:
+  `management.endpoints.web.exposure.include: health,info,metrics`
+
+## 4. API Stability
+- Annotate controllers with OpenAPI/Swagger (`@Tag`, `@Operation`, `@ApiResponse`).
+- Enable graceful shutdown: `server.shutdown: graceful`.
+