agent-workflow-kit-cli 1.0.0-mvp

package/templates/common/AGENTS.md.hbs

@@ -0,0 +1,44 @@
+# Repository Agent Guidelines
+
+This repository implements the `agent-workflow-kit-cli` configuration standards for AI coding agents.
+
+---
+
+## 🚀 AI Agent Step-by-Step Execution Workflow
+
+AI agents MUST follow this strict 5-step workflow for any task:
+
+### 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.
+
+### 2. 📝 Step 2: Formulate Implementation Plan
+- Document your proposed design 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.
+
+### 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.
+
+### 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.
+
+---
+
+## ⚙️ 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.
+
+<!-- AWK-START: STACK_PACK -->
+{{{stackContent}}}
+<!-- AWK-END: STACK_PACK -->

package/templates/fastapi/AGENTS.md.hbs

@@ -0,0 +1,28 @@
+## 🐍 Python FastAPI Guidelines
+
+### 🏗️ Architecture & Router-Service-Repository Conventions
+Follow a clean layering architecture. Separate HTTP routing, business logic, and database operations:
+
+```text
+app/
+  core/           # Config, database setup
+  models/         # SQLAlchemy or SQLModel entities
+  schemas/        # Pydantic validation models
+  crud/           # Database repositories/CRUD operations
+  services/       # Business logic layer
+  api/            # Route controllers
+    v1/
+      endpoints/  # API Routers
+```
+
+### ⚙️ Coding Guidelines
+- **Dependency Injection:** Use FastAPI's `Depends` explicitly for injecting database sessions, security credentials, and custom services.
+- **Strict Typing:** Always annotate function arguments and return types. Use Pydantic's `response_model` or type hints to enforce validation.
+- **Asynchronous Handlers:** Prefer `async def` for I/O bound endpoints.
+
+### 🧪 Testing & Verification
+Before completing a task, run the following verification pipeline locally:
+```bash
+ruff check .
+pytest
+```

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

@@ -0,0 +1,22 @@
+# 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.
+
+## 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`.
+
+## 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.

package/templates/fastapi/skills/fastapi-feature/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: fastapi-feature
+description: Generates or extends a Python FastAPI endpoint/module
+---
+
+Follow this workflow to create a new API router or feature slice in the project.
+
+Inputs:
+- featureName: Name of the feature (e.g., `items`)
+- endpointPath: Base path of the router (e.g., `/items`)
+
+Steps:
+1. Create schema models under `app/schemas/` using Pydantic.
+2. Create CRUD operations under `app/crud/` using SQLAlchemy.
+3. Write business logic service under `app/services/` if needed.
+4. Implement the API router under `app/api/v1/endpoints/`.
+5. Write integration tests using pytest and AsyncClient.
+6. Verify code formatting and linting using Ruff.

package/templates/react-ts/AGENTS.md.hbs

@@ -0,0 +1,47 @@
+## React + TypeScript Guidelines
+
+### Architecture & Feature Conventions
+Use a feature-first structure. Keep route wiring thin, and place feature UI, hooks, data clients, and types together:
+
+```text
+src/
+  app/                  # App shell, router, providers
+  features/
+    billing/
+      components/
+        BillingPanel.tsx
+      hooks/
+        useBilling.ts
+      services/
+        billingClient.ts
+      types.ts
+      index.ts
+  shared/
+    components/
+    hooks/
+    utils/
+```
+
+### Component, Hook, and State Rules
+- Components render UI and delegate fetching, subscriptions, timers, and other side effects to custom hooks.
+- Custom hooks own reusable stateful logic and must start with `use`.
+- Prefer local component state for isolated interactions.
+- Use Context API for low-frequency cross-tree state such as theme, auth session, or app configuration.
+- Use Zustand only for shared state with frequent updates or cross-feature coordination.
+- Keep feature state close to the feature before moving it to `shared/`.
+
+### TypeScript Standards
+- Use strict TypeScript. Avoid `any`; prefer explicit domain types and discriminated unions.
+- Define feature-local interfaces and types near the code that owns them.
+- Export from feature `index.ts` files only when another module needs the API.
+- Use absolute imports from `@/`; do not add deep relative imports like `../../`.
+
+### Testing & Verification
+Before completing a React + TypeScript change, run the project validation pipeline:
+
+```bash
+npm run lint
+npm run typecheck
+npm run test -- --run
+npm run build
+```

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

@@ -0,0 +1,34 @@
+# 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.
+
+## 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`.
+
+## 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.
+
+## 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.
+
+## 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.

package/templates/react-ts/skills/react-feature/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: react-feature
+description: Generates or extends a React + TypeScript feature with component, hook, types, styles, and tests
+---
+
+Follow this workflow to create a new React + TypeScript feature or route.
+
+Inputs:
+- featureName: Name of the feature (e.g., `billing`)
+- targetPath: Feature or route folder to extend
+- userFlow: Brief description of the user-visible behavior
+
+Steps:
+1. Inspect neighboring features, routes, shared components, and import aliases before editing.
+2. Define feature-local types first, including loading, error, empty, and success state shapes.
+3. Create or update the custom hook that owns fetching, side effects, derived state, and cleanup.
+4. Create or update PascalCase components that render UI and delegate logic to hooks.
+5. Add styles using the project's existing styling approach; do not introduce a new styling system.
+6. Wire the feature into the route or parent component through the smallest public API needed.
+7. Add tests for component behavior and hook logic when branching, async work, or cleanup is present.
+8. Run validations:
+   - `npm run lint`
+   - `npm run typecheck`
+   - `npm run test -- --run`
+   - `npm run build`

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

@@ -0,0 +1,79 @@
+## ☕ Java Spring Boot Guidelines
+
+### 🏗️ Architecture & Package Conventions
+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/
+  customer/
+    dto/
+      CreateCustomerRequest.java
+      CustomerResponse.java
+    entity/
+      Customer.java
+    mapper/
+      CustomerMapper.java
+    repository/
+      CustomerRepository.java
+    service/
+      CustomerService.java
+      impl/CustomerServiceImpl.java
+    web/
+      CustomerController.java
+```
+
+Corresponding test directories must match the feature layout exactly:
+```text
+src/test/java/com/acme/app/
+  customer/
+    repository/
+      CustomerRepositoryTest.java  # Custom query repository slice tests
+    service/
+      CustomerServiceTest.java     # Business logic unit tests (using Mockito)
+    web/
+      CustomerControllerTest.java  # Web MVC slice tests
+```
+
+### ⚙️ 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`).
+- **Layer Separation:** Keep controllers thin; delegate all business rules, transactions, and transformations to the service layer.
+
+### 🛠️ Tooling & Quality Standards
+The project runs Checkstyle for static analysis and Spotless for code formatting. Ensure code conforms to these rules before pushing.
+```xml
+<!-- Checkstyle & Spotless Maven Configurations -->
+<plugin>
+  <groupId>org.apache.maven.plugins</groupId>
+  <artifactId>maven-checkstyle-plugin</artifactId>
+  <configuration>
+    <configLocation>checkstyle.xml</configLocation>
+  </configuration>
+</plugin>
+<plugin>
+  <groupId>com.diffplug.spotless</groupId>
+  <artifactId>spotless-maven-plugin</artifactId>
+  <configuration>
+    <java>
+      <googleJavaFormat/>
+    </java>
+  </configuration>
+</plugin>
+```
+
+### 🧪 Testing Guidelines
+All edits must pass local verification tests before completion:
+
+| Test Type | Requirement | Done Criteria |
+| :--- | :--- | :--- |
+| **Service Unit Test** | Always | Verify business rules; mock repository and external dependencies using Mockito. |
+| **`@WebMvcTest`** | For new/modified controllers | Verify API routing, status codes, payload serialization, and constraint validation errors. |
+| **`@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. |
+
+### 🚀 Verification Commands
+Before completing a task, run the following verification pipeline locally:
+```bash
+./mvnw clean test
+./mvnw verify
+```

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

@@ -0,0 +1,14 @@
+# Java Spring Boot Style Constraints
+
+Enforce strict coding style and layer definitions in this repository.
+
+## 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/skills/spring-feature/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: spring-feature
+description: Generates or extends a Java Spring Boot feature module
+---
+
+Follow this workflow to create a new REST feature or API slice in the project.
+
+Inputs:
+- featureName: Name of the feature (e.g., `billing`)
+- endpointPath: Base path of the controller (e.g., `/api/v1/billing`)
+
+Steps:
+1. Examine neighboring feature packages for error handler conventions and mappings.
+2. Create the target feature package under the designated project folder.
+3. Implement layers:
+   - `entity/`: Database models.
+   - `repository/`: Spring Data JPA interface.
+   - `dto/`: Request/Response schemas with jakarta.validation annotations.
+   - `service/`: Service interfaces and implementations.
+   - `web/`: Controller class exposing `@RestController` with proper mappings.
+4. Create tests:
+   - Service Unit Tests using Mockito.
+   - `@WebMvcTest` for Controller routing, payloads, and validation.
+   - `@DataJpaTest` for custom queries.
+5. Run validations:
+   - `./mvnw verify`