@heyai-rules/pilo-masterkit 1.2.2 → 3.1.0

package/.agent/skills/java-coding-standards/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: java-coding-standards
+description: "Java coding standards for Spring Boot services: naming, immutability, Optional usage, streams, exceptions, generics, and project layout."
+origin: ECC
+---
+
+# Java Coding Standards
+
+Standards for readable, maintainable Java (17+) code in Spring Boot services.
+
+## When to Activate
+
+- Writing or reviewing Java code in Spring Boot projects
+- Enforcing naming, immutability, or exception handling conventions
+- Working with records, sealed classes, or pattern matching (Java 17+)
+- Reviewing use of Optional, streams, or generics
+- Structuring packages and project layout
+
+## Core Principles
+
+- Prefer clarity over cleverness
+- Immutable by default; minimize shared mutable state
+- Fail fast with meaningful exceptions
+- Consistent naming and package structure
+
+## Naming
+
+```java
+// PASS: Classes/Records: PascalCase
+public class MarketService {}
+public record Money(BigDecimal amount, Currency currency) {}
+
+// PASS: Methods/fields: camelCase
+private final MarketRepository marketRepository;
+public Market findBySlug(String slug) {}
+
+// PASS: Constants: UPPER_SNAKE_CASE
+private static final int MAX_PAGE_SIZE = 100;
+```
+
+## Immutability
+
+```java
+// PASS: Favor records and final fields
+public record MarketDto(Long id, String name, MarketStatus status) {}
+
+public class Market {
+  private final Long id;
+  private final String name;
+  // getters only, no setters
+}
+```
+
+## Optional Usage
+
+```java
+// PASS: Return Optional from find* methods
+Optional<Market> market = marketRepository.findBySlug(slug);
+
+// PASS: Map/flatMap instead of get()
+return market
+    .map(MarketResponse::from)
+    .orElseThrow(() -> new EntityNotFoundException("Market not found"));
+```
+
+## Streams Best Practices
+
+```java
+// PASS: Use streams for transformations, keep pipelines short
+List<String> names = markets.stream()
+    .map(Market::name)
+    .filter(Objects::nonNull)
+    .toList();
+
+// FAIL: Avoid complex nested streams; prefer loops for clarity
+```
+
+## Exceptions
+
+- Use unchecked exceptions for domain errors; wrap technical exceptions with context
+- Create domain-specific exceptions (e.g., `MarketNotFoundException`)
+- Avoid broad `catch (Exception ex)` unless rethrowing/logging centrally
+
+```java
+throw new MarketNotFoundException(slug);
+```
+
+## Generics and Type Safety
+
+- Avoid raw types; declare generic parameters
+- Prefer bounded generics for reusable utilities
+
+```java
+public <T extends Identifiable> Map<Long, T> indexById(Collection<T> items) { ... }
+```
+
+## Project Structure (Maven/Gradle)
+
+```
+src/main/java/com/example/app/
+  config/
+  controller/
+  service/
+  repository/
+  domain/
+  dto/
+  util/
+src/main/resources/
+  application.yml
+src/test/java/... (mirrors main)
+```
+
+## Formatting and Style
+
+- Use 2 or 4 spaces consistently (project standard)
+- One public top-level type per file
+- Keep methods short and focused; extract helpers
+- Order members: constants, fields, constructors, public methods, protected, private
+
+## Code Smells to Avoid
+
+- Long parameter lists → use DTO/builders
+- Deep nesting → early returns
+- Magic numbers → named constants
+- Static mutable state → prefer dependency injection
+- Silent catch blocks → log and act or rethrow
+
+## Logging
+
+```java
+private static final Logger log = LoggerFactory.getLogger(MarketService.class);
+log.info("fetch_market slug={}", slug);
+log.error("failed_fetch_market slug={}", slug, ex);
+```
+
+## Null Handling
+
+- Accept `@Nullable` only when unavoidable; otherwise use `@NonNull`
+- Use Bean Validation (`@NotNull`, `@NotBlank`) on inputs
+
+## Testing Expectations
+
+- JUnit 5 + AssertJ for fluent assertions
+- Mockito for mocking; avoid partial mocks where possible
+- Favor deterministic tests; no hidden sleeps
+
+**Remember**: Keep code intentional, typed, and observable. Optimize for maintainability over micro-optimizations unless proven necessary.

package/.agent/skills/jira-integration/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: jira-integration
+description: Use this skill when retrieving Jira tickets, analyzing requirements, updating ticket status, adding comments, or transitioning issues. Provides Jira API patterns via MCP or direct REST calls.
+origin: ECC
+---
+
+# Jira Integration Skill
+
+Retrieve, analyze, and update Jira tickets directly from your AI coding workflow. Supports both **MCP-based** (recommended) and **direct REST API** approaches.
+
+## When to Activate
+
+- Fetching a Jira ticket to understand requirements
+- Extracting testable acceptance criteria from a ticket
+- Adding progress comments to a Jira issue
+- Transitioning a ticket status (To Do → In Progress → Done)
+- Linking merge requests or branches to a Jira issue
+- Searching for issues by JQL query
+
+## Prerequisites
+
+### Option A: MCP Server (Recommended)
+
+Install the `mcp-atlassian` MCP server. This exposes Jira tools directly to your AI agent.
+
+**Requirements:**
+- Python 3.10+
+- `uvx` (from `uv`), installed via your package manager or the official `uv` installation documentation
+
+**Add to your MCP config** (e.g., `~/.claude.json` → `mcpServers`):
+
+```json
+{
+  "jira": {
+    "command": "uvx",
+    "args": ["mcp-atlassian==0.21.0"],
+    "env": {
+      "JIRA_URL": "https://YOUR_ORG.atlassian.net",
+      "JIRA_EMAIL": "your.email@example.com",
+      "JIRA_API_TOKEN": "your-api-token"
+    },
+    "description": "Jira issue tracking — search, create, update, comment, transition"
+  }
+}
+```
+
+> **Security:** Never hardcode secrets. Prefer setting `JIRA_URL`, `JIRA_EMAIL`, and `JIRA_API_TOKEN` in your system environment (or a secrets manager). Only use the MCP `env` block for local, uncommitted config files.
+
+**To get a Jira API token:**
+1. Go to <https://id.atlassian.com/manage-profile/security/api-tokens>
+2. Click **Create API token**
+3. Copy the token — store it in your environment, never in source code
+
+### Option B: Direct REST API
+
+If MCP is not available, use the Jira REST API v3 directly via `curl` or a helper script.
+
+**Required environment variables:**
+
+| Variable | Description |
+|----------|-------------|
+| `JIRA_URL` | Your Jira instance URL (e.g., `https://yourorg.atlassian.net`) |
+| `JIRA_EMAIL` | Your Atlassian account email |
+| `JIRA_API_TOKEN` | API token from id.atlassian.com |
+
+Store these in your shell environment, secrets manager, or an untracked local env file. Do not commit them to the repo.
+
+## MCP Tools Reference
+
+When the `mcp-atlassian` MCP server is configured, these tools are available:
+
+| Tool | Purpose | Example |
+|------|---------|---------|
+| `jira_search` | JQL queries | `project = PROJ AND status = "In Progress"` |
+| `jira_get_issue` | Fetch full issue details by key | `PROJ-1234` |
+| `jira_create_issue` | Create issues (Task, Bug, Story, Epic) | New bug report |
+| `jira_update_issue` | Update fields (summary, description, assignee) | Change assignee |
+| `jira_transition_issue` | Change status | Move to "In Review" |
+| `jira_add_comment` | Add comments | Progress update |
+| `jira_get_sprint_issues` | List issues in a sprint | Active sprint review |
+| `jira_create_issue_link` | Link issues (Blocks, Relates to) | Dependency tracking |
+| `jira_get_issue_development_info` | See linked PRs, branches, commits | Dev context |
+
+> **Tip:** Always call `jira_get_transitions` before transitioning — transition IDs vary per project workflow.
+
+## Direct REST API Reference
+
+### Fetch a Ticket
+
+```bash
+curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$JIRA_URL/rest/api/3/issue/PROJ-1234" | jq '{
+    key: .key,
+    summary: .fields.summary,
+    status: .fields.status.name,
+    priority: .fields.priority.name,
+    type: .fields.issuetype.name,
+    assignee: .fields.assignee.displayName,
+    labels: .fields.labels,
+    description: .fields.description
+  }'
+```
+
+### Fetch Comments
+
+```bash
+curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$JIRA_URL/rest/api/3/issue/PROJ-1234?fields=comment" | jq '.fields.comment.comments[] | {
+    author: .author.displayName,
+    created: .created[:10],
+    body: .body
+  }'
+```
+
+### Add a Comment
+
+```bash
+curl -s -X POST -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "body": {
+      "version": 1,
+      "type": "doc",
+      "content": [{
+        "type": "paragraph",
+        "content": [{"type": "text", "text": "Your comment here"}]
+      }]
+    }
+  }' \
+  "$JIRA_URL/rest/api/3/issue/PROJ-1234/comment"
+```
+
+### Transition a Ticket
+
+```bash
+# 1. Get available transitions
+curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
+  "$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions" | jq '.transitions[] | {id, name: .name}'
+
+# 2. Execute transition (replace TRANSITION_ID)
+curl -s -X POST -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"transition": {"id": "TRANSITION_ID"}}' \
+  "$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions"
+```
+
+### Search with JQL
+
+```bash
+curl -s -G -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
+  --data-urlencode "jql=project = PROJ AND status = 'In Progress'" \
+  "$JIRA_URL/rest/api/3/search"
+```
+
+## Analyzing a Ticket
+
+When retrieving a ticket for development or test automation, extract:
+
+### 1. Testable Requirements
+- **Functional requirements** — What the feature does
+- **Acceptance criteria** — Conditions that must be met
+- **Testable behaviors** — Specific actions and expected outcomes
+- **User roles** — Who uses this feature and their permissions
+- **Data requirements** — What data is needed
+- **Integration points** — APIs, services, or systems involved
+
+### 2. Test Types Needed
+- **Unit tests** — Individual functions and utilities
+- **Integration tests** — API endpoints and service interactions
+- **E2E tests** — User-facing UI flows
+- **API tests** — Endpoint contracts and error handling
+
+### 3. Edge Cases & Error Scenarios
+- Invalid inputs (empty, too long, special characters)
+- Unauthorized access
+- Network failures or timeouts
+- Concurrent users or race conditions
+- Boundary conditions
+- Missing or null data
+- State transitions (back navigation, refresh, etc.)
+
+### 4. Structured Analysis Output
+
+```
+Ticket: PROJ-1234
+Summary: [ticket title]
+Status: [current status]
+Priority: [High/Medium/Low]
+Test Types: Unit, Integration, E2E
+
+Requirements:
+1. [requirement 1]
+2. [requirement 2]
+
+Acceptance Criteria:
+- [ ] [criterion 1]
+- [ ] [criterion 2]
+
+Test Scenarios:
+- Happy Path: [description]
+- Error Case: [description]
+- Edge Case: [description]
+
+Test Data Needed:
+- [data item 1]
+- [data item 2]
+
+Dependencies:
+- [dependency 1]
+- [dependency 2]
+```
+
+## Updating Tickets
+
+### When to Update
+
+| Workflow Step | Jira Update |
+|---|---|
+| Start work | Transition to "In Progress" |
+| Tests written | Comment with test coverage summary |
+| Branch created | Comment with branch name |
+| PR/MR created | Comment with link, link issue |
+| Tests passing | Comment with results summary |
+| PR/MR merged | Transition to "Done" or "In Review" |
+
+### Comment Templates
+
+**Starting Work:**
+```
+Starting implementation for this ticket.
+Branch: feat/PROJ-1234-feature-name
+```
+
+**Tests Implemented:**
+```
+Automated tests implemented:
+
+Unit Tests:
+- [test file 1] — [what it covers]
+- [test file 2] — [what it covers]
+
+Integration Tests:
+- [test file] — [endpoints/flows covered]
+
+All tests passing locally. Coverage: XX%
+```
+
+**PR Created:**
+```
+Pull request created:
+[PR Title](https://github.com/org/repo/pull/XXX)
+
+Ready for review.
+```
+
+**Work Complete:**
+```
+Implementation complete.
+
+PR merged: [link]
+Test results: All passing (X/Y)
+Coverage: XX%
+```
+
+## Security Guidelines
+
+- **Never hardcode** Jira API tokens in source code or skill files
+- **Always use** environment variables or a secrets manager
+- **Add `.env`** to `.gitignore` in every project
+- **Rotate tokens** immediately if exposed in git history
+- **Use least-privilege** API tokens scoped to required projects
+- **Validate** that credentials are set before making API calls — fail fast with a clear message
+
+## Troubleshooting
+
+| Error | Cause | Fix |
+|---|---|---|
+| `401 Unauthorized` | Invalid or expired API token | Regenerate at id.atlassian.com |
+| `403 Forbidden` | Token lacks project permissions | Check token scopes and project access |
+| `404 Not Found` | Wrong ticket key or base URL | Verify `JIRA_URL` and ticket key |
+| `spawn uvx ENOENT` | IDE cannot find `uvx` on PATH | Use full path (e.g., `~/.local/bin/uvx`) or set PATH in `~/.zprofile` |
+| Connection timeout | Network/VPN issue | Check VPN connection and firewall rules |
+
+## Best Practices
+
+- Update Jira as you go, not all at once at the end
+- Keep comments concise but informative
+- Link rather than copy — point to PRs, test reports, and dashboards
+- Use @mentions if you need input from others
+- Check linked issues to understand full feature scope before starting
+- If acceptance criteria are vague, ask for clarification before writing code

package/.agent/skills/jpa-patterns/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: jpa-patterns
+description: JPA/Hibernate patterns for entity design, relationships, query optimization, transactions, auditing, indexing, pagination, and pooling in Spring Boot.
+origin: ECC
+---
+
+# JPA/Hibernate Patterns
+
+Use for data modeling, repositories, and performance tuning in Spring Boot.
+
+## When to Activate
+
+- Designing JPA entities and table mappings
+- Defining relationships (@OneToMany, @ManyToOne, @ManyToMany)
+- Optimizing queries (N+1 prevention, fetch strategies, projections)
+- Configuring transactions, auditing, or soft deletes
+- Setting up pagination, sorting, or custom repository methods
+- Tuning connection pooling (HikariCP) or second-level caching
+
+## Entity Design
+
+```java
+@Entity
+@Table(name = "markets", indexes = {
+  @Index(name = "idx_markets_slug", columnList = "slug", unique = true)
+})
+@EntityListeners(AuditingEntityListener.class)
+public class MarketEntity {
+  @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
+  private Long id;
+
+  @Column(nullable = false, length = 200)
+  private String name;
+
+  @Column(nullable = false, unique = true, length = 120)
+  private String slug;
+
+  @Enumerated(EnumType.STRING)
+  private MarketStatus status = MarketStatus.ACTIVE;
+
+  @CreatedDate private Instant createdAt;
+  @LastModifiedDate private Instant updatedAt;
+}
+```
+
+Enable auditing:
+```java
+@Configuration
+@EnableJpaAuditing
+class JpaConfig {}
+```
+
+## Relationships and N+1 Prevention
+
+```java
+@OneToMany(mappedBy = "market", cascade = CascadeType.ALL, orphanRemoval = true)
+private List<PositionEntity> positions = new ArrayList<>();
+```
+
+- Default to lazy loading; use `JOIN FETCH` in queries when needed
+- Avoid `EAGER` on collections; use DTO projections for read paths
+
+```java
+@Query("select m from MarketEntity m left join fetch m.positions where m.id = :id")
+Optional<MarketEntity> findWithPositions(@Param("id") Long id);
+```
+
+## Repository Patterns
+
+```java
+public interface MarketRepository extends JpaRepository<MarketEntity, Long> {
+  Optional<MarketEntity> findBySlug(String slug);
+
+  @Query("select m from MarketEntity m where m.status = :status")
+  Page<MarketEntity> findByStatus(@Param("status") MarketStatus status, Pageable pageable);
+}
+```
+
+- Use projections for lightweight queries:
+```java
+public interface MarketSummary {
+  Long getId();
+  String getName();
+  MarketStatus getStatus();
+}
+Page<MarketSummary> findAllBy(Pageable pageable);
+```
+
+## Transactions
+
+- Annotate service methods with `@Transactional`
+- Use `@Transactional(readOnly = true)` for read paths to optimize
+- Choose propagation carefully; avoid long-running transactions
+
+```java
+@Transactional
+public Market updateStatus(Long id, MarketStatus status) {
+  MarketEntity entity = repo.findById(id)
+      .orElseThrow(() -> new EntityNotFoundException("Market"));
+  entity.setStatus(status);
+  return Market.from(entity);
+}
+```
+
+## Pagination
+
+```java
+PageRequest page = PageRequest.of(pageNumber, pageSize, Sort.by("createdAt").descending());
+Page<MarketEntity> markets = repo.findByStatus(MarketStatus.ACTIVE, page);
+```
+
+For cursor-like pagination, include `id > :lastId` in JPQL with ordering.
+
+## Indexing and Performance
+
+- Add indexes for common filters (`status`, `slug`, foreign keys)
+- Use composite indexes matching query patterns (`status, created_at`)
+- Avoid `select *`; project only needed columns
+- Batch writes with `saveAll` and `hibernate.jdbc.batch_size`
+
+## Connection Pooling (HikariCP)
+
+Recommended properties:
+```
+spring.datasource.hikari.maximum-pool-size=20
+spring.datasource.hikari.minimum-idle=5
+spring.datasource.hikari.connection-timeout=30000
+spring.datasource.hikari.validation-timeout=5000
+```
+
+For PostgreSQL LOB handling, add:
+```
+spring.jpa.properties.hibernate.jdbc.lob.non_contextual_creation=true
+```
+
+## Caching
+
+- 1st-level cache is per EntityManager; avoid keeping entities across transactions
+- For read-heavy entities, consider second-level cache cautiously; validate eviction strategy
+
+## Migrations
+
+- Use Flyway or Liquibase; never rely on Hibernate auto DDL in production
+- Keep migrations idempotent and additive; avoid dropping columns without plan
+
+## Testing Data Access
+
+- Prefer `@DataJpaTest` with Testcontainers to mirror production
+- Assert SQL efficiency using logs: set `logging.level.org.hibernate.SQL=DEBUG` and `logging.level.org.hibernate.orm.jdbc.bind=TRACE` for parameter values
+
+**Remember**: Keep entities lean, queries intentional, and transactions short. Prevent N+1 with fetch strategies and projections, and index for your read/write paths.