thanh-kit 2.5.0

package/templates/commands/investigate.md

@@ -0,0 +1,324 @@
+# Investigate Feature: $ARGUMENTS
+
+Investigate and explain how an existing feature or logic works using structured knowledge model construction.
+
+**KEY PRINCIPLE**: This is a **READ-ONLY exploration** - no code changes. Focus on understanding and explaining.
+
+## Variables
+
+- **FEATURE**: $ARGUMENTS (the feature/logic to investigate)
+- **ANALYSIS_FILE**: `ai_task_analysis_notes/$ARGUMENTS-investigation.ai_task_analysis_notes_temp.md`
+
+---
+
+## INPUT: Scout Output Integration
+
+**If preceded by `/scout`:**
+
+1. **Use the numbered file list** from Scout results as your analysis targets
+2. **Prioritize in this order:**
+   - HIGH PRIORITY files (Domain Entities, Commands, Queries, Event Handlers, Controllers, Jobs, Consumers)
+   - Suggested Starting Points (if provided)
+   - MEDIUM PRIORITY files (Services, Helpers, Components)
+3. **Skip redundant discovery** - Scout already searched the codebase
+4. **Reference files by Scout's numbers** in your analysis (e.g., "File #3 from Scout")
+
+**Scout Output Format Reference:**
+```markdown
+### HIGH PRIORITY (Analyze First)
+| # | File | Purpose |
+|---|------|---------|
+| 1 | `path/Entity.cs` | Core domain entity |
+
+### Suggested Starting Points
+1. **[Most relevant file]** - [Why]
+```
+
+**If NO Scout output available:** Proceed with Phase 1A discovery as normal.
+
+---
+
+## PHASE 1A: INITIALIZATION AND DISCOVERY
+
+### Step 1: Initialize Analysis File
+
+Create the analysis file at `ai_task_analysis_notes/[feature-name]-investigation.ai_task_analysis_notes_temp.md` with these required sections:
+
+```markdown
+## Metadata
+
+```markdown
+**Original Prompt:** [User's investigation question]
+**Task Description:** [What we're investigating]
+**Source Code Structure:** See ai-prompt-context.md
+```
+
+## Progress
+
+- **Phase**: 1A
+- **Items Processed**: 0
+- **Total Items**: 0
+- **Current Operation**: "initialization"
+- **Current Focus**: "[feature summary]"
+
+## Errors
+
+[None yet]
+
+## Assumption Validations
+
+| Assumption | Status | Evidence |
+|------------|--------|----------|
+| ... | Pending/Validated/Invalid | ... |
+
+## File List
+
+[Numbered list of files to analyze]
+
+## Knowledge Graph
+
+[Detailed analysis of each file]
+```
+
+### Step 2: Semantic Discovery
+
+Search for related code using multiple patterns:
+
+**Primary Patterns:**
+```
+*Command*{Feature}*           # CQRS Commands
+*Query*{Feature}*             # CQRS Queries
+*{Feature}*EventHandler*      # Entity Event Handlers
+*{Feature}*Consumer*          # Message Bus Consumers
+*{Feature}*BackgroundJob*     # Background Jobs
+*{Feature}*Controller*        # API Controllers
+```
+
+**Secondary Patterns:**
+```
+.*EventHandler.*{Feature}|{Feature}.*EventHandler
+.*BackgroundJob.*{Feature}|{Feature}.*BackgroundJob
+.*Consumer.*{Feature}|{Feature}.*Consumer
+.*Service.*{Feature}|{Feature}.*Service
+.*Helper.*{Feature}|{Feature}.*Helper
+```
+
+**File Types:** `**/*.{cs,ts,html}`
+
+### Step 3: Prioritize Files
+
+**HIGH PRIORITY (Must Analyze):**
+1. Domain Entities (`Domain/Entities/`)
+2. CQRS Commands (`UseCaseCommands/`)
+3. CQRS Queries (`UseCaseQueries/`)
+4. Entity Event Handlers (`UseCaseEvents/`)
+5. Controllers (`Controllers/`)
+6. Background Jobs (`*BackgroundJob*.cs`)
+7. Message Bus Consumers (`*Consumer.cs`)
+8. Frontend Components (`*.component.ts`)
+
+**MEDIUM PRIORITY:**
+- Services, Helpers, DTOs, Repositories
+
+Save ALL file paths as numbered list under `## File List` in analysis file.
+
+---
+
+## PHASE 1B: KNOWLEDGE GRAPH CONSTRUCTION
+
+### Step 1: Batch Processing Setup
+
+Count total files, split into batches of 10. Use TodoWrite to create tasks:
+
+```
+- [ ] Analyze batch 1 (files 1-10)
+- [ ] Analyze batch 2 (files 11-20)
+...
+```
+
+### Step 2: File Analysis Schema
+
+For each file, add to `## Knowledge Graph` with this structure:
+
+```markdown
+### [#] [FileName]
+
+- **filePath**: Full path to file
+- **type**: Entity | Command | Query | EventHandler | Consumer | Controller | Job | Component | Service
+- **architecturalPattern**: CQRS | Repository | EventSourcing | MessageBus | etc.
+- **content**: Summary of purpose and logic
+- **symbols**: Key classes, interfaces, methods
+- **dependencies**: Imported modules / using statements
+- **businessContext**: How it contributes to business requirements
+- **referenceFiles**: Other files using this file's symbols
+- **relevanceScore**: 1-10 (10 = most relevant)
+- **evidenceLevel**: verified | inferred
+- **uncertainties**: Aspects you're unsure about
+- **platformAbstractions**: Base classes used (PlatformCqrsCommand, PlatformEntity, etc.)
+- **serviceContext**: Which microservice owns this
+- **dependencyInjection**: DI registrations
+- **genericTypeParameters**: Generic type relationships
+
+#### Targeted Analysis
+
+**For Backend:**
+- authorizationPolicies, commands, queries, domainEntities
+- repositoryPatterns, businessRuleImplementations
+
+**For Consumers:**
+- messageBusMessage: The `*BusMessage` type consumed
+- messageBusProducers: Files that SEND this message (grep across ALL services)
+- crossServiceIntegration: How services communicate
+
+**For Frontend:**
+- componentHierarchy, routeConfig, stateManagementStores
+- dataBindingPatterns, validationStrategies
+```
+
+### Step 3: Cross-Service Analysis (CRITICAL for Consumers)
+
+When analyzing `*Consumer.cs` files extending `PlatformApplicationMessageBusConsumer<T>`:
+
+1. Identify the `*BusMessage` type
+2. Grep search ALL services for files that **publish** this message
+3. Document producer files and their service locations
+4. Map the cross-service data flow
+
+---
+
+## PHASE 2: CODE FLOW TRACING
+
+### Step 1: Entry Points
+
+Identify how the feature is triggered:
+- API Endpoint → Controller → Command/Query Handler
+- UI Action → Component → API Service → Backend
+- Scheduled Job → BackgroundJob → Handler
+- Message → Consumer → Handler
+
+### Step 2: Trace Execution Path
+
+Document in analysis file:
+
+```markdown
+## Data Flow
+
+[Request] → [Controller] → [Handler] → [Repository] → [Response]
+                              ↓
+                       [Event Handler] → [Side Effects]
+                              ↓
+                       [Message Bus] → [Consumer in Other Service]
+```
+
+### Step 3: Side Effects Mapping
+
+- Entity events raised
+- Messages published to bus
+- External service calls
+- Database operations
+- Notifications triggered
+
+---
+
+## PHASE 3: PRESENT FINDINGS
+
+### Output Format
+
+```markdown
+## Executive Summary
+
+[1-2 paragraph direct answer to the investigation question]
+
+## How It Works
+
+### 1. [Entry Point]
+[Explanation with `file:line` reference]
+
+### 2. [Core Processing]
+[Explanation with `file:line` reference]
+
+### 3. [Side Effects]
+[Explanation with `file:line` reference]
+
+## Key Files
+
+| File | Type | Purpose | Relevance |
+|------|------|---------|-----------|
+| `path/file.cs:123` | Command | [Purpose] | 10/10 |
+
+## Data Flow Diagram
+
+```
+[Visual text diagram of the flow]
+```
+
+## Platform Patterns Used
+
+- **Pattern**: How it's applied
+- **Pattern**: How it's applied
+
+## Cross-Service Integration
+
+| Source Service | Message | Target Service | Consumer |
+|----------------|---------|----------------|----------|
+| ... | ... | ... | ... |
+
+## Unresolved Questions
+
+- [Question 1]
+- [Question 2]
+
+## Want to Know More?
+
+- [Related topic 1]
+- [Related topic 2]
+```
+
+---
+
+## Anti-Hallucination Protocol
+
+Before ANY claim, verify:
+
+1. "What assumptions am I making?"
+2. "Have I verified with actual code evidence?"
+3. "Could I be wrong about how this works?"
+
+### Verification Checklist
+
+- [ ] Found actual code evidence for each claim?
+- [ ] Traced the full code path?
+- [ ] Checked cross-service message flows?
+- [ ] Documented ALL findings with `file:line`?
+- [ ] Answered the original question?
+- [ ] Listed unresolved questions?
+
+**If ANY unchecked → DO MORE INVESTIGATION**
+
+---
+
+## Progress Tracking
+
+Update `## Progress` section after each batch:
+
+```markdown
+- **Phase**: 1B
+- **Items Processed**: 20
+- **Total Items**: 35
+- **Current Operation**: "analyzing batch 3"
+- **Current Focus**: "Event Handlers"
+```
+
+---
+
+## Quick Reference
+
+| Looking for... | Search in... |
+|----------------|--------------|
+| Entity CRUD | `UseCaseCommands/`, `UseCaseQueries/` |
+| Business logic | `Domain/Entities/`, `*Service.cs` |
+| Side effects | `UseCaseEvents/`, `*EventHandler.cs` |
+| Cross-service | `*Consumer.cs`, `*BusMessage.cs` |
+| API endpoints | `Controllers/`, `*Controller.cs` |
+| Frontend | `libs/apps-domains/`, `*.component.ts` |
+| Background processing | `*BackgroundJob*.cs`, `*Job.cs` |

package/templates/commands/journal.md

@@ -0,0 +1,7 @@
+---
+description: ⚡ Write some journal entries.
+---
+
+Use the `journal-writer` subagent to explore the memories and recent code changes, and write some journal entries.
+Journal entries should be concise and focused on the most important events, key changes, impacts, and decisions.
+Keep journal entries in the `./docs/journals/` directory.

package/templates/commands/kanban.md

@@ -0,0 +1,101 @@
+---
+description: AI agent orchestration board (Coming Soon)
+arguments:
+  - name: dir
+    description: Plans directory (default: ./plans)
+    required: false
+---
+
+Plans dashboard with progress tracking and timeline visualization.
+
+## Usage
+
+- `/kanban` - View dashboard for ./plans directory
+- `/kanban plans/` - View dashboard for specific directory
+- `/kanban --stop` - Stop running server
+
+## Features
+
+- Plan cards with progress bars
+- Phase status breakdown (completed, in-progress, pending)
+- Timeline/Gantt visualization
+- Activity heatmap
+- Issue and branch links
+
+## Execution
+
+**IMPORTANT:** Run server as Claude Code background task using `run_in_background: true` with the Bash tool. This makes the server visible in `/tasks` and manageable via `KillShell`.
+
+Check if this script is located in the current workspace or in `$HOME/.claude/skills/plans-kanban` directory:
+- If in current workspace: `$SKILL_DIR_PATH` = `./.claude/skills/plans-kanban/`
+- If in home directory: `$SKILL_DIR_PATH` = `$HOME/.claude/skills/plans-kanban/`
+
+### Stop Server
+
+If `--stop` flag is provided:
+
+```bash
+node $SKILL_DIR_PATH/scripts/server.cjs --stop
+```
+
+### Start Server
+
+Otherwise, run the kanban server as CC background task with `--foreground` flag (keeps process alive for CC task management):
+
+```bash
+# Determine plans directory
+INPUT_DIR="{{dir}}"
+PLANS_DIR="${INPUT_DIR:-./plans}"
+
+# Start kanban dashboard
+node $SKILL_DIR_PATH/scripts/server.cjs \
+  --dir "$PLANS_DIR" \
+  --host 0.0.0.0 \
+  --open \
+  --foreground
+```
+
+**Critical:** When calling the Bash tool:
+- Set `run_in_background: true` to run as CC background task
+- Set `timeout: 300000` (5 minutes) to prevent premature termination
+- Parse JSON output and report URL to user
+
+Example Bash tool call:
+```json
+{
+  "command": "node .claude/skills/plans-kanban/scripts/server.cjs --dir \"./plans\" --host 0.0.0.0 --open --foreground",
+  "run_in_background": true,
+  "timeout": 300000,
+  "description": "Start kanban server in background"
+}
+```
+
+After starting, parse the JSON output (e.g., `{"success":true,"url":"http://localhost:3500/kanban?dir=...","networkUrl":"http://192.168.1.x:3500/kanban?dir=..."}`) and report:
+- Local URL for browser access
+- Network URL for remote device access (if available)
+- Inform user that server is now running as CC background task (visible in `/tasks`)
+
+**CRITICAL:** MUST display the FULL URL including path and query string. NEVER truncate to just `host:port`. The full URL is required for direct access.
+
+## Future Plans
+
+The `/kanban` command will evolve into **VibeKanban-inspired** AI agent orchestration:
+
+### Phase 1 (Current - MVP)
+- ✅ Task board with progress tracking
+- ✅ Visual representation of plans/tasks
+- ✅ Click to view plan details
+
+### Phase 2 (Worktree Integration)
+- Create tasks → spawn git worktrees
+- Assign agents to tasks
+- Track agent progress per worktree
+
+### Phase 3 (Full Orchestration)
+- Parallel agent execution monitoring
+- Code diff/review interface
+- PR creation workflow
+- Agent output streaming
+- Conflict detection
+
+Track progress: https://github.com/claudekit/claudekit-engineer/issues/189

package/templates/commands/lint.md

@@ -0,0 +1,47 @@
+---
+description: Run linters and fix issues for backend or frontend
+allowed-tools: Bash, Read, Edit, Glob, TodoWrite
+---
+
+Run linting: $ARGUMENTS
+
+## Instructions
+
+1. **Parse arguments**:
+   - `backend` or `be` → Run .NET analyzers
+   - `frontend` or `fe` → Run ESLint/Prettier
+   - `fix` → Auto-fix issues where possible
+   - No argument → Run both, report only
+
+2. **For Backend (.NET)**:
+
+   ```bash
+   dotnet build EasyPlatform.sln /p:TreatWarningsAsErrors=false
+   ```
+
+   - Check for analyzer warnings (CA*, IDE*, etc.)
+   - Report code style violations
+
+3. **For Frontend (Angular/Nx)**:
+
+   ```bash
+   cd src/PlatformExampleAppWeb
+   nx lint playground-text-snippet
+   nx lint platform-core
+   ```
+
+   With auto-fix:
+
+   ```bash
+   nx lint playground-text-snippet --fix
+   npx prettier --write "apps/**/*.{ts,html,scss}" "libs/**/*.{ts,html,scss}"
+   ```
+
+4. **Report format**:
+   - Group issues by severity (error, warning, info)
+   - Show file paths and line numbers
+   - Suggest fixes for common issues
+
+5. **Auto-fix behavior**:
+   - If `fix` argument provided, apply safe auto-fixes
+   - Report what was fixed vs what needs manual attention

package/templates/commands/migration.md

@@ -0,0 +1,111 @@
+# Create Migration: $ARGUMENTS
+
+Create a data or schema migration following EasyPlatform patterns.
+
+## Phase 1: Analyze Requirements
+
+1. **Parse migration description** from: $ARGUMENTS
+2. **Identify migration type:**
+    - Schema migration (EF Core) - for SQL Server/PostgreSQL table changes
+    - Data migration (PlatformDataMigrationExecutor) - for data transformations
+    - MongoDB migration (PlatformMongoMigrationExecutor) - for MongoDB changes
+
+3. **Search for existing patterns:**
+    - `src/PlatformExampleApp/*/Persistence/Migrations/` for schema migrations
+    - Search for `PlatformDataMigrationExecutor` implementations
+
+## Phase 2: Design Migration
+
+1. **Determine affected entities and tables**
+2. **Plan rollback strategy if applicable**
+3. **Consider data volume and performance:**
+    - Use paging for large datasets (PageSize: 200-500)
+    - Set `dismissSendEvent: true` if entity events not needed
+    - Use `checkDiff: false` for bulk updates
+
+## Phase 3: Generate Migration
+
+Follow naming convention: `YYYYMMDDHHMMSS_MigrationName`
+
+**For EF Core Schema Migration:**
+
+```bash
+dotnet ef migrations add MigrationName --project src/PlatformExampleApp/{Service}/{Service}.Persistence
+```
+
+**For Data Migration (SQL Server/PostgreSQL):**
+
+```csharp
+public class YYYYMMDDHHMMSS_MigrationName : PlatformDataMigrationExecutor<{Service}DbContext>
+{
+    public override string Name => "YYYYMMDDHHMMSS_MigrationName";
+    public override DateTime? OnlyForDbsCreatedBeforeDate => new(YYYY, MM, DD);
+    public override bool AllowRunInBackgroundThread => true;
+
+    public override async Task Execute({Service}DbContext dbContext)
+    {
+        var queryBuilder = repository.GetQueryBuilder(q => q.Where(FilterExpr()));
+        await RootServiceProvider.ExecuteInjectScopedPagingAsync(
+            maxItemCount: await repository.CountAsync(q => queryBuilder(q)),
+            pageSize: 200,
+            ExecutePaging,
+            queryBuilder);
+    }
+
+    private static async Task<List<Entity>> ExecutePaging(
+        int skip, int take,
+        Func<IQueryable<Entity>, IQueryable<Entity>> qb,
+        IRepo<Entity> repo,
+        IPlatformUnitOfWorkManager uow)
+    {
+        using var unitOfWork = uow.Begin();
+        var items = await repo.GetAllAsync(q => qb(q).OrderBy(e => e.Id).Skip(skip).Take(take));
+        // Apply transformations
+        await repo.UpdateManyAsync(items, dismissSendEvent: true, checkDiff: false);
+        await unitOfWork.CompleteAsync();
+        return items;
+    }
+}
+```
+
+**For MongoDB Migration:**
+
+```csharp
+internal sealed class YYYYMMDDHHMMSS_MigrationName : PlatformMongoMigrationExecutor<{Service}DbContext>
+{
+    public override string Name => "YYYYMMDDHHMMSS_MigrationName";
+    public override DateTime? OnlyForDbInitBeforeDate => new(YYYY, MM, DD);
+    public override DateTime? ExpirationDate => new(YYYY, MM, DD); // Optional: auto-delete after date
+
+    public override async Task Execute({Service}DbContext dbContext)
+    {
+        // Ensure indexes
+        await dbContext.EnsureInboxBusMessageCollectionIndexesAsync(true);
+        await dbContext.EnsureOutboxBusMessageCollectionIndexesAsync(true);
+
+        // Or custom index/data operations
+        var collection = dbContext.GetCollection<Entity>();
+        await collection.Indexes.CreateOneAsync(
+            new CreateIndexModel<Entity>(
+                Builders<Entity>.IndexKeys.Ascending(e => e.Field),
+                new CreateIndexOptions { Unique = true }));
+    }
+}
+```
+
+## Phase 4: Verify
+
+- [ ] Migration is idempotent (safe to run multiple times)
+- [ ] Large datasets use paging
+- [ ] Proper error handling
+- [ ] Unit of work for transactions
+- [ ] `OnlyForDbsCreatedBeforeDate` set correctly
+- [ ] Tested with sample data
+
+## Phase 5: Wait for Approval
+
+**CRITICAL:** Present your migration design and wait for explicit user approval before creating files.
+
+---
+
+Use `backend-data-migration` skill for detailed guidance.

package/templates/commands/performance.md

@@ -0,0 +1,110 @@
+# Analyze Performance: $ARGUMENTS
+
+Analyze and optimize performance for: $ARGUMENTS
+
+## Phase 1: Identify Bottleneck Type
+
+1. **Database queries:**
+    - N+1 query problems
+    - Missing indexes
+    - Inefficient projections
+    - Full table scans
+
+2. **API endpoint latency:**
+    - Serialization overhead
+    - Unnecessary data loading
+    - Missing caching
+    - Sequential operations that could be parallel
+
+3. **Frontend rendering:**
+    - Excessive change detection
+    - Large component trees
+    - Missing OnPush strategy
+    - Unnecessary re-renders
+
+4. **Memory issues:**
+    - Subscription leaks
+    - Large object retention
+    - Missing cleanup in ngOnDestroy
+
+## Phase 2: Investigation
+
+### Backend Analysis
+
+1. **Check repository patterns:**
+
+    ```csharp
+    // ✅ Eager load related entities
+    await repository.GetAllAsync(expr, ct, e => e.RelatedEntity, e => e.AnotherRelated)
+
+    // ❌ N+1 problem - separate query per item
+    foreach (item in items) { await repo.GetById(item.RelatedId) }
+    ```
+
+2. **Review query builders:**
+
+    ```csharp
+    // ✅ Use projections to reduce data transfer
+    .Select(e => new { e.Id, e.Name, e.Status })
+
+    // ❌ Loading full entities when only IDs needed
+    .Select(e => e).ToList().Select(e => e.Id)
+    ```
+
+3. **Check for parallel operations:**
+
+    ```csharp
+    // ✅ Parallel tuple queries
+    var (total, items, counts) = await (
+        repository.CountAsync(queryBuilder, ct),
+        repository.GetAllAsync(queryBuilder.PageBy(skip, take), ct),
+        repository.GetGroupedCountsAsync(queryBuilder, ct)
+    );
+
+    // ❌ Sequential when independent
+    var total = await repository.CountAsync(queryBuilder, ct);
+    var items = await repository.GetAllAsync(queryBuilder.PageBy(skip, take), ct);
+    ```
+
+4. **Review full-text search usage:**
+    ```csharp
+    // ✅ Use IPlatformFullTextSearchPersistenceService
+    .PipeIf(searchText.IsNotNullOrEmpty(), q =>
+        searchService.Search(q, searchText, Entity.SearchColumns()))
+    ```
+
+### Frontend Analysis
+
+1. **Check signal usage and change detection**
+2. **Review store patterns for unnecessary emissions**
+3. **Verify `untilDestroyed()` on all subscriptions**
+4. **Check for `trackBy` in `@for` loops**
+5. **Review `observerLoadingErrorState` usage**
+
+## Phase 3: Profiling Commands
+
+```bash
+# Backend - Check EF Core query logging
+# Enable in appsettings.Development.json:
+# "Logging": { "LogLevel": { "Microsoft.EntityFrameworkCore.Database.Command": "Information" } }
+
+# Frontend - Angular DevTools profiler
+# Use Angular DevTools Chrome extension
+```
+
+## Phase 4: Optimization Plan
+
+Present findings with:
+
+- Current performance metrics (if measurable)
+- Root cause identification with file:line references
+- Targeted fix recommendations
+- Expected improvement rationale
+
+## Phase 5: Wait for Approval
+
+**CRITICAL:** Present your findings and optimization plan. Wait for explicit user approval before making changes.
+
+---
+
+Use `arch-performance-optimization` skill for detailed guidance.