@atlashub/smartstack-cli 1.1.0

package/templates/commands/ai-prompt.md

@@ -0,0 +1,315 @@
+# /ai-prompt - Gestion Prompts IA SmartStack
+
+> **Synergie Skill/Commande:**
+> - **Skill** (`templates/skills/ai-prompt/`) → Invocation automatique par Claude
+> - **Commande** (`/ai-prompt`) → Invocation manuelle par l'utilisateur
+
+---
+
+## ARGUMENTS
+
+```
+/ai-prompt <action> [options]
+```
+
+| Action | Description |
+|--------|-------------|
+| `create` | Creer un nouveau prompt avec blocks |
+| `schema` | Creer un schema de validation |
+| `integrate` | Integrer l'IA dans un service existant |
+| `test` | Tester un prompt avec des variables |
+
+---
+
+## WORKFLOW
+
+### /ai-prompt create
+
+Cree un nouveau prompt avec ses blocks.
+
+**Questions:**
+1. Code du prompt ? (kebab-case)
+2. Nom descriptif ?
+3. Description ?
+4. Type ? (Analyzer, Generator, Classifier, Assistant)
+5. Blocks a creer ? (System, User, Examples)
+6. Schema de validation ? (oui/non)
+
+**Actions:**
+1. Creer le prompt via API ou seed
+2. Ajouter les blocks
+3. Creer le schema si requis
+4. Lier le schema au prompt
+
+### /ai-prompt schema
+
+Cree un schema de validation JSON.
+
+**Questions:**
+1. Code du schema ?
+2. Nom ?
+3. Proprietes requises ?
+4. Type .NET associe ?
+
+**Actions:**
+1. Generer le JSON Schema
+2. Creer le DTO C# correspondant
+3. Ajouter dans la base de donnees
+
+### /ai-prompt integrate
+
+Integre l'execution IA dans un service existant.
+
+**Questions:**
+1. Quel service modifier ?
+2. Quelle methode ajouter ? (Analyze, Generate, Classify)
+3. Quel prompt utiliser ?
+4. Retour type ?
+
+**Actions:**
+1. Injecter `IAiCompletionService`
+2. Creer la methode d'execution
+3. Ajouter la validation du resultat
+4. Logger l'execution
+
+### /ai-prompt test
+
+Teste un prompt avec des variables.
+
+**Questions:**
+1. Quel prompt tester ?
+2. Variables a injecter ?
+
+**Actions:**
+1. Afficher le prompt rendu
+2. Executer contre le provider
+3. Afficher le resultat et les metriques
+
+---
+
+## TEMPLATES
+
+### Template Prompt Block System
+
+```csharp
+new CreateBlockRequest
+{
+    BlockType = PromptBlockType.System,
+    Label = "Instructions",
+    Content = @"Tu es un expert en $DOMAIN.
+Analyse le contenu fourni et retourne:
+- $OUTPUT_1
+- $OUTPUT_2
+- $OUTPUT_3
+
+Reponds UNIQUEMENT en JSON valide correspondant au schema fourni.",
+    DisplayOrder = 1,
+    IsRequired = true
+}
+```
+
+### Template Prompt Block User
+
+```csharp
+new CreateBlockRequest
+{
+    BlockType = PromptBlockType.User,
+    Label = "Input",
+    Content = "Contenu: {{content}}\nContexte: {{context}}",
+    DisplayOrder = 2,
+    IsRequired = true
+}
+```
+
+### Template JSON Schema
+
+```json
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "required": ["$PROP_1", "$PROP_2"],
+    "properties": {
+        "$PROP_1": {
+            "type": "string",
+            "description": "$DESCRIPTION_1"
+        },
+        "$PROP_2": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 10,
+            "description": "$DESCRIPTION_2"
+        },
+        "$PROP_3": {
+            "type": "array",
+            "items": { "type": "string" },
+            "maxItems": 5,
+            "description": "$DESCRIPTION_3"
+        }
+    }
+}
+```
+
+### Template DTO Result
+
+```csharp
+// Application/AI/{Entity}AnalysisResult.cs
+
+public class {Entity}AnalysisResult
+{
+    [JsonPropertyName("$PROP_1")]
+    public string $Prop1 { get; set; } = string.Empty;
+
+    [JsonPropertyName("$PROP_2")]
+    public int $Prop2 { get; set; }
+
+    [JsonPropertyName("$PROP_3")]
+    public List<string> $Prop3 { get; set; } = new();
+}
+```
+
+### Template Service Integration
+
+```csharp
+public async Task<{Entity}AnalysisResult?> Analyze{Entity}Async(
+    Guid entityId,
+    CancellationToken ct)
+{
+    var entity = await _context.{Entity}s.FindAsync(entityId);
+    if (entity == null) return null;
+
+    try
+    {
+        var result = await _aiCompletionService
+            .ExecutePromptByCodeWithValidationAsync<{Entity}AnalysisResult>(
+                "{entity}-analyzer",
+                new Dictionary<string, object>
+                {
+                    ["content"] = entity.Content,
+                    ["context"] = entity.Context ?? ""
+                },
+                cancellationToken: ct);
+
+        if (result.Success && result.IsValid)
+        {
+            _logger.LogInformation(
+                "{Entity} {EntityId} analyzed in {Ms}ms: {Result}",
+                entityId,
+                result.ExecutionTimeMs,
+                result.Data.$Prop1);
+
+            return result.Data;
+        }
+
+        if (!result.Success)
+        {
+            _logger.LogError(
+                "AI analysis failed for {Entity} {EntityId}: {Error}",
+                entityId, result.Error);
+        }
+        else if (!result.IsValid)
+        {
+            _logger.LogWarning(
+                "AI response invalid for {Entity} {EntityId}: {Errors}",
+                entityId, string.Join(", ", result.ValidationErrors));
+        }
+
+        return null;
+    }
+    catch (Exception ex)
+    {
+        _logger.LogError(ex, "Exception analyzing {Entity} {EntityId}", entityId);
+        return null;
+    }
+}
+```
+
+### Template Controller Endpoint
+
+```csharp
+[HttpPost("{id}/analyze")]
+[RequirePermission(Permissions.$Module.$Entity.Update)]
+[ProducesResponseType(typeof({Entity}AnalysisResult), StatusCodes.Status200OK)]
+[ProducesResponseType(StatusCodes.Status400BadRequest)]
+[ProducesResponseType(StatusCodes.Status404NotFound)]
+public async Task<ActionResult<{Entity}AnalysisResult>> Analyze{Entity}(
+    Guid id,
+    CancellationToken ct)
+{
+    var result = await _service.Analyze{Entity}Async(id, ct);
+
+    if (result == null)
+        return BadRequest(new { message = "Analysis failed" });
+
+    return Ok(result);
+}
+```
+
+### Template Frontend Button
+
+```tsx
+import { Sparkles, Loader2 } from 'lucide-react';
+
+interface AiAnalyzeButtonProps {
+  entityId: string;
+  onResult: (result: AnalysisResult) => void;
+}
+
+export function AiAnalyzeButton({ entityId, onResult }: AiAnalyzeButtonProps) {
+  const [loading, setLoading] = useState(false);
+
+  const handleAnalyze = async () => {
+    setLoading(true);
+    try {
+      const result = await {module}Api.analyze(entityId);
+      onResult(result);
+      toast.success('Analyse terminee');
+    } catch (error) {
+      toast.error('Erreur lors de l\'analyse');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <button
+      onClick={handleAnalyze}
+      disabled={loading}
+      className="inline-flex items-center gap-2 px-4 py-2 bg-purple-600 text-white rounded-lg hover:bg-purple-700 disabled:opacity-50"
+    >
+      {loading ? (
+        <Loader2 className="w-4 h-4 animate-spin" />
+      ) : (
+        <Sparkles className="w-4 h-4" />
+      )}
+      Analyser avec IA
+    </button>
+  );
+}
+```
+
+---
+
+## FICHIERS CLES
+
+| Fichier | Role |
+|---------|------|
+| `Domain/AI/Prompts/Prompt.cs` | Entite prompt |
+| `Domain/AI/Schemas/OutputSchema.cs` | Schema validation |
+| `Application/Common/Interfaces/IAiCompletionService.cs` | Interface |
+| `Infrastructure/Services/AI/AiCompletionService.cs` | Implementation |
+| `Infrastructure/Services/AI/PromptService.cs` | Gestion prompts |
+
+---
+
+## REGLES
+
+1. **TOUJOURS** creer un schema de validation pour les reponses structurees
+2. **TOUJOURS** creer le DTO C# correspondant au schema
+3. **TOUJOURS** logger les executions avec tokens et duree
+4. **TOUJOURS** gerer les erreurs (API down, validation)
+5. **JAMAIS** exposer les prompts systeme au frontend
+6. **JAMAIS** hardcoder les cles API
+
+---
+
+User: $ARGUMENTS

package/templates/commands/apex/1-analyze.md

@@ -0,0 +1,100 @@
+---
+description: Analyze phase - gather all context and create analysis report
+argument-hint: <task-description>
+---
+
+You are an analysis specialist. Your mission is to gather ALL relevant context before implementation.
+
+**You need to ULTRA THINK before launching agents.**
+
+## Workflow
+
+1. **SETUP TASK FOLDER**: Create organized workspace in .claude/tasks
+   - Find next task number: Check `.claude/tasks/` for existing folders
+   - Parse task description to create kebab-case name
+   - Create `.claude/tasks/nn-task-name/` folder structure
+   - **EXAMPLE**: "Add user authentication" → `.claude/tasks/01-add-user-authentication/`
+   - **CRITICAL**: Always use `.claude/tasks/` directory for task storage
+
+2. **ULTRA THINK**: Plan analysis strategy
+   - **CRITICAL**: Know EXACTLY what to search for before launching agents
+   - Identify key concepts, files, patterns to find
+   - Determine which sources need analysis (codebase/docs/web)
+   - List specific questions each agent should answer
+
+3. **LAUNCH PARALLEL ANALYSIS**: Gather context from all sources
+   - **Codebase exploration** (`explore-codebase` agent):
+     - Find similar implementations to use as examples
+     - Locate files that need modification
+     - Identify existing patterns and conventions
+     - Search for related utilities and helpers
+
+   - **Documentation exploration** (`explore-docs` agent):
+     - Search library docs for APIs and patterns
+     - Find best practices for tools being used
+     - Gather code examples from official docs
+
+   - **Web research** (`websearch` agent):
+     - Research latest approaches and solutions
+     - Find community examples and patterns
+     - Gather architectural guidance
+
+   - **CRITICAL**: Launch ALL agents in parallel in a single message
+
+4. **SYNTHESIZE FINDINGS**: Create comprehensive analysis report
+   - Combine findings from all agents
+   - Organize by topic/concern
+   - Include file paths with line numbers (e.g., `src/auth.ts:42`)
+   - List relevant examples found in codebase
+   - Document key patterns and conventions to follow
+   - Note any dependencies or prerequisites
+
+5. **SAVE ANALYSIS**: Write to `analyze.md`
+   - Save to `.claude/tasks/nn-task-name/analyze.md`
+   - **Structure**:
+     ```markdown
+     # Task: [Description]
+
+     ## Codebase Context
+     [Findings from codebase exploration]
+
+     ## Documentation Insights
+     [Key information from docs]
+
+     ## Research Findings
+     [Web research results]
+
+     ## Key Files
+     - `path/to/file.ts:line` - Purpose
+
+     ## Patterns to Follow
+     [Existing conventions]
+
+     ## Dependencies
+     [Prerequisites and related systems]
+     ```
+
+6. **REPORT**: Summarize to user
+   - Confirm task folder created
+   - Highlight key findings
+   - Note any concerns or blockers discovered
+   - Suggest next step: Run the following command to create implementation plan:
+     ```
+     /apex:plan <task-folder>
+     ```
+
+## Execution Rules
+
+- **PARALLEL EXECUTION**: All agents must run simultaneously for speed
+- **ULTRA THINK FIRST**: Never launch agents without clear search strategy
+- **COMPREHENSIVE**: Gather more context than seems necessary
+- **ORGANIZED**: Structure findings for easy planning phase
+- **FILE REFERENCES**: Always include file paths with line numbers
+
+## Priority
+
+Context depth > Speed. Missing context causes failed implementations.
+
+---
+
+User: $ARGUMENTS

package/templates/commands/apex/2-plan.md

@@ -0,0 +1,145 @@
+---
+description: Planning phase - create detailed implementation strategy from analysis
+argument-hint: <task-folder-path>
+---
+
+You are a strategic planning specialist. Transform analysis findings into executable implementation plans.
+
+**You need to ULTRA THINK about the complete implementation strategy.**
+
+> **INSTRUCTION CLAUDE:** The `AskUserQuestion({...})` blocks are instructions to use the `AskUserQuestion` tool **interactively**. You MUST execute the tool with these parameters to get the user's response BEFORE continuing.
+
+## Workflow
+
+1. **VALIDATE INPUT**: Verify task folder exists
+   - Check that `.claude/tasks/<task-folder>/` exists
+   - Verify `analyze.md` file is present
+   - **CRITICAL**: If missing, instruct user to run:
+     ```
+     /apex:analyze
+     ```
+
+2. **READ ANALYSIS**: Load all context
+   - Read `.claude/tasks/<task-folder>/analyze.md` completely
+   - Review all codebase findings
+   - Note patterns and conventions discovered
+   - Identify files to modify and examples to follow
+
+3. **ULTRA THINK PLANNING**: Design comprehensive strategy
+   - **CRITICAL**: Think through ENTIRE implementation before writing
+   - Consider all edge cases and dependencies
+   - Plan file changes in logical dependency order
+   - Identify test requirements
+   - Plan documentation updates if needed
+
+4. **ASK FOR CLARITY**: Resolve ambiguities
+   - **STOP**: If anything is unclear about requirements
+   - Use AskUserQuestion for:
+     - Multiple valid approaches
+     - Unclear technical choices
+     - Scope boundaries
+     - Architecture decisions
+   - **NEVER ASSUME**: Always clarify before planning
+
+5. **CREATE DETAILED PLAN**: Write file-by-file implementation guide
+   - **Structure**: Group by file, NOT by feature
+   - **Format**: Action-oriented, no code snippets
+   - **Specificity**: Exact changes needed in each file
+   - Include:
+     - Core functionality changes (file by file)
+     - Test files to create/modify
+     - Documentation to update
+     - Configuration changes
+     - Migration steps if needed
+
+6. **SAVE PLAN**: Write to `plan.md`
+   - Save to `.claude/tasks/<task-folder>/plan.md`
+   - **Structure**:
+     ```markdown
+     # Implementation Plan: [Task Name]
+
+     ## Overview
+     [High-level strategy and approach]
+
+     ## Dependencies
+     [Files/systems that must be done first]
+
+     ## File Changes
+
+     ### `path/to/file1.ts`
+     - Action 1: What to change and why
+     - Action 2: Specific modification needed
+     - Consider: Edge cases or important context
+
+     ### `path/to/file2.ts`
+     - Action: What needs to change
+     - Pattern: Follow example from `other/file.ts:123`
+
+     ## Testing Strategy
+     - Tests to create: `path/to/test.spec.ts`
+     - Tests to update: `path/to/existing.test.ts`
+     - Manual verification steps
+
+     ## Documentation
+     - Update: `README.md` section X
+     - Add: New docs for feature Y
+
+     ## Rollout Considerations
+     [Migration steps, feature flags, breaking changes]
+     ```
+
+7. **VERIFY COMPLETENESS**: Check plan quality
+   - **All files identified**: Nothing missing
+   - **Logical order**: Dependencies handled
+   - **Clear actions**: No ambiguous steps
+   - **Test coverage**: All paths tested
+   - **In scope**: No scope creep
+
+8. **REPORT**: Summarize to user
+   - Confirm plan created
+   - Highlight key implementation steps
+   - Note any risks or complexity
+   - Suggest next step: Run one of these commands:
+     - To divide plan into tasks:
+       ```
+       /apex:tasks <task-folder>
+       ```
+     - To execute plan directly:
+       ```
+       /apex:execute <task-folder>
+       ```
+
+## Plan Quality Guidelines
+
+### Good Plan Entry
+```markdown
+### `src/auth/middleware.ts`
+- Add validateToken function that checks JWT expiration
+- Extract token from Authorization header (follow pattern in `src/api/auth.ts:45`)
+- Return 401 if token invalid or expired
+- Consider: Handle both Bearer and custom token formats
+```
+
+### Bad Plan Entry
+```markdown
+### `src/auth/middleware.ts`
+- Add authentication
+- Fix security issues
+```
+
+## Execution Rules
+
+- **NO CODE SNIPPETS**: Plans describe actions, not implementations
+- **FILE-CENTRIC**: Organize by file, not by feature
+- **ACTIONABLE**: Every item must be clear and executable
+- **CONTEXTUALIZED**: Reference examples from analysis findings
+- **SCOPED**: Stay within task boundaries
+- **STOP AND ASK**: Clarify ambiguities before proceeding
+
+## Priority
+
+Clarity > Completeness. Every step must be unambiguous and executable.
+
+---
+
+User: $ARGUMENTS