@nextsparkjs/core 0.1.0-beta.8 → 0.1.0-beta.82

package/dist/presets/ai-workflow/claude/commands/task:explain.md

@@ -1,276 +0,0 @@
----
-description: Interactive code walkthrough for understanding a completed feature
----
-
-# Task Explain - Interactive Feature Learning
-
-ultrathink You are providing an interactive code walkthrough to help the user understand a feature.
-
-**Session or Feature to explain:**
-{{{ input }}}
-
----
-
-## Your Mission
-
-Create an interactive learning experience that guides the user through the code implementation step by step. The goal is to help them deeply understand how the feature works, not just see the code.
-
----
-
-## Phase 1: Context Gathering
-
-### If a session path is provided:
-
-```typescript
-const sessionPath = `.claude/sessions/${sessionName}/`
-
-// Load session files to understand the feature
-await Read(`${sessionPath}/requirements.md`)
-await Read(`${sessionPath}/plan.md`)
-await Read(`${sessionPath}/tests.md`)
-```
-
-### If no session, analyze the feature:
-
-1. Ask the user which feature/area they want to understand
-2. Use Glob and Grep to identify all related files
-3. Read key files to understand the implementation scope
-
----
-
-## Phase 2: Build the Learning Index
-
-After understanding the feature scope, create a **Learning Index** - a structured progression from foundation to completion.
-
-### Learning Index Structure:
-
-```markdown
-## Learning Index: [Feature Name]
-
-**Total Items:** [N items]
-**Estimated Walkthrough:** [N sections of 3 items each]
-
-### Foundation Layer
-1. [Entry point / Configuration] - `path/to/file.ts`
-2. [Core types/interfaces] - `path/to/types.ts`
-3. [Database schema (if applicable)] - `path/to/migration.sql`
-
-### Data Layer
-4. [API route handler] - `app/api/.../route.ts`
-5. [Business logic / services] - `core/lib/.../service.ts`
-6. [Validation schemas] - `core/lib/.../schema.ts`
-
-### UI Layer
-7. [Main component] - `app/(dashboard)/.../page.tsx`
-8. [Sub-components] - `core/components/.../Component.tsx`
-9. [Hooks / state management] - `core/hooks/useFeature.ts`
-
-### Integration Layer
-10. [Tests] - `tests/cypress/e2e/.../feature.cy.ts`
-11. [Translations] - `messages/en.json (namespace)`
-12. [Selectors] - `tests/cypress/fixtures/selectors.json`
-```
-
-### Index Creation Rules:
-
-1. **Start from the root** - Begin with config, types, or database schema
-2. **Follow the data flow** - DB -> API -> Frontend -> UI
-3. **Group logically** - Related files together
-4. **Include line references** - Note key functions/methods with `file:line`
-5. **Maximum 15 items** - Keep it digestible, skip trivial files
-
----
-
-## Phase 3: Interactive Walkthrough
-
-Present the index to the user, then begin the walkthrough.
-
-### Initial Presentation:
-
-```markdown
-## Feature: [Name]
-
-I've analyzed the implementation and created a learning path with [N] items.
-
-**Learning Index:**
-[Show full index]
-
----
-
-Let's start with the first 3 items. I'll explain each file, highlight key methods, and show how they connect.
-
-Ready to begin?
-```
-
-### For Each Section (3 items):
-
-1. **Read the files** in that section
-2. **Explain the purpose** of each file (1-2 sentences)
-3. **Show key code snippets** with explanations
-4. **Explain connections** between the files
-5. **Highlight important patterns** (registry usage, hooks, etc.)
-
-### Section Presentation Format:
-
-```markdown
-## Section [N]: [Section Name]
-
-### 1. [File Name] (`path/to/file.ts`)
-
-**Purpose:** [What this file does and why it exists]
-
-**Key Code:**
-```typescript
-// path/to/file.ts:45-60
-[relevant code snippet]
-```
-
-**Explanation:**
-- [Bullet point explaining what this code does]
-- [How it connects to other parts]
-
----
-
-### 2. [Next File]...
-
----
-
-## Connections in This Section:
-- [File A] provides [X] which [File B] uses to [Y]
-- [Pattern observed]: [e.g., "Uses TanStack Query for server state"]
-
----
-
-**Questions about this section?** Or type "continue" for the next 3 items.
-```
-
----
-
-## Interaction Guidelines
-
-### Balance Information Load:
-
-- **DO:** Focus on key methods and their purpose
-- **DO:** Show how pieces connect together
-- **DO:** Highlight patterns and best practices used
-- **DON'T:** Show every line of code
-- **DON'T:** Explain obvious TypeScript syntax
-- **DON'T:** Overwhelm with too many details at once
-
-### User Commands:
-
-- **"continue"** - Proceed to next 3 items
-- **"explain [X]"** - Deep dive into specific concept
-- **"show [function]"** - Display full function code
-- **"how does [X] connect to [Y]?"** - Explain relationship
-- **"skip to [section]"** - Jump to specific section
-- **"summary"** - Provide high-level summary of entire feature
-
-### Adaptive Depth:
-
-- If user asks questions, provide deeper explanations
-- If user says "continue" quickly, maintain current depth
-- If user seems confused, simplify and add more context
-
----
-
-## Example Interaction
-
-**Claude:**
-```
-## Feature: Scheduled Actions
-
-I've analyzed the implementation and created a learning path with 12 items across 4 sections.
-
-**Learning Index:**
-
-### Foundation (Items 1-3)
-1. Database schema - `core/migrations/017_scheduled_actions_table.sql`
-2. Core types - `core/lib/scheduled-actions/types.ts`
-3. Registry integration - `core/lib/registries/entity-registry.ts`
-
-### Backend (Items 4-6)
-4. API handler - `app/api/v1/scheduled-actions/route.ts`
-5. Action executor - `core/lib/scheduled-actions/executor.ts`
-6. Cron endpoint - `app/api/v1/cron/scheduled-actions/route.ts`
-
-### Frontend (Items 7-9)
-7. List page - `app/devtools/scheduled-actions/page.tsx`
-8. Action form - `core/components/devtools/scheduled-actions/ActionForm.tsx`
-9. Status display - `core/components/devtools/scheduled-actions/StatusBadge.tsx`
-
-### Testing (Items 10-12)
-10. API tests - `tests/cypress/e2e/api/scheduled-actions/`
-11. UAT tests - `tests/cypress/e2e/uat/scheduled-actions/`
-12. Jest units - `core/tests/jest/lib/scheduled-actions/`
-
-Ready to start with the Foundation section?
-```
-
-**User:** yes
-
-**Claude:**
-```
-## Section 1: Foundation
-
-### 1. Database Schema (`core/migrations/017_scheduled_actions_table.sql`)
-
-**Purpose:** Defines the persistent storage structure for scheduled actions.
-
-**Key Code:**
-```sql
--- core/migrations/017_scheduled_actions_table.sql:12-28
-CREATE TABLE "scheduledAction" (
-  "id" TEXT PRIMARY KEY DEFAULT gen_random_uuid(),
-  "name" TEXT NOT NULL,
-  "actionType" TEXT NOT NULL,
-  "schedule" TEXT NOT NULL,  -- cron expression
-  "payload" JSONB DEFAULT '{}',
-  "status" TEXT DEFAULT 'active',
-  "lastRun" TIMESTAMP WITH TIME ZONE,
-  "nextRun" TIMESTAMP WITH TIME ZONE,
-  "createdAt" TIMESTAMP WITH TIME ZONE DEFAULT NOW()
-);
-```
-
-**Key Points:**
-- Uses camelCase column names (project convention)
-- `schedule` stores cron expressions like "0 9 * * *"
-- `payload` is JSONB for flexible action parameters
-- `status` tracks if action is active/paused/error
-
----
-
-### 2. Core Types (`core/lib/scheduled-actions/types.ts`)
-
-[...continues with next file...]
-```
-
----
-
-## Completion
-
-After all sections are covered:
-
-```markdown
-## Walkthrough Complete!
-
-You've explored all [N] items covering:
-- [Section 1]: [brief summary]
-- [Section 2]: [brief summary]
-- ...
-
-**Key Takeaways:**
-1. [Main pattern/architecture used]
-2. [Important design decision]
-3. [How it integrates with the rest of the system]
-
-**Want to:**
-- Ask any remaining questions?
-- See a specific part in more detail?
-- Move on to `/task:demo` to see the feature in action?
-```
-
----
-
-**Now analyze the feature and create the Learning Index.**

package/dist/presets/ai-workflow/claude/commands/task:pending.md

@@ -1,299 +0,0 @@
----
-description: Document pending items discovered during development for future iterations
----
-
-# Task Pending - Document Deferred Items
-
-You are documenting a pending item discovered during development that will be addressed in a future iteration.
-
-**Session and Pending Description:**
-{{{ input }}}
-
----
-
-## Your Mission
-
-Document pending items properly so they can be addressed in future versions:
-
-1. **Capture the pending item** with full context
-2. **Classify priority and category**
-3. **Document impact** of not resolving now
-4. **Provide recommendations** for future iteration
-5. **Update pendings.md** in session folder
-
----
-
-## Pending Documentation Protocol
-
-### Step 1: Read Session Context
-
-```typescript
-const sessionPath = extractSessionPath(input)
-
-// Read current pendings
-await Read(`${sessionPath}/pendings.md`)
-
-// Read context for understanding
-await Read(`${sessionPath}/clickup_task.md`)
-await Read(`${sessionPath}/plan.md`)
-await Read(`${sessionPath}/progress.md`)
-```
-
-### Step 2: Classify Pending Item
-
-**Ask user about the pending:**
-
-```typescript
-await AskUserQuestion({
-  questions: [
-    {
-      header: "Priority",
-      question: "What priority is this pending item?",
-      options: [
-        { label: "Alta", description: "Should be done in next iteration" },
-        { label: "Media", description: "Important but can wait" },
-        { label: "Baja", description: "Nice to have, low urgency" }
-      ],
-      multiSelect: false
-    },
-    {
-      header: "Category",
-      question: "What category is this pending?",
-      options: [
-        { label: "Feature", description: "Missing or incomplete feature" },
-        { label: "Bug", description: "Known issue not blocking" },
-        { label: "Refactor", description: "Code improvement opportunity" },
-        { label: "Performance", description: "Optimization needed" },
-        { label: "Security", description: "Security enhancement" },
-        { label: "UX", description: "User experience improvement" },
-        { label: "Documentation", description: "Docs needed" }
-      ],
-      multiSelect: false
-    },
-    {
-      header: "Reason",
-      question: "Why is this being deferred?",
-      options: [
-        { label: "Tiempo insuficiente", description: "Not enough time in current sprint" },
-        { label: "Fuera del alcance actual", description: "Out of scope for this version" },
-        { label: "Requiere decisión de producto", description: "Needs PM decision" },
-        { label: "Dependencia externa", description: "Blocked by external factor" },
-        { label: "Complejidad técnica alta", description: "Too complex for current iteration" }
-      ],
-      multiSelect: true
-    }
-  ]
-})
-```
-
-### Step 3: Document in pendings.md
-
-```typescript
-// Get current pending count
-const currentPendings = await Read(`${sessionPath}/pendings.md`)
-const pendingCount = countExistingPendings(currentPendings) + 1
-
-await Edit({
-  file_path: `${sessionPath}/pendings.md`,
-  old_string: "No hay pendientes documentados para esta sesión.",
-  new_string: `### P${pendingCount}: ${pendingTitle}
-
-**Detectado por:** ${agentName}
-**Fecha:** ${date}
-**Prioridad:** ${priority}
-**Categoría:** ${category}
-
-**Descripción:**
-${description}
-
-**Razón para Postergar:**
-${reasons.map(r => `- [x] ${r}`).join('\n')}
-
-**Impacto de No Resolverlo:**
-- Funcionalidad afectada: ${affectedFunctionality}
-- Usuarios afectados: ${affectedUsers}
-- Riesgo: ${riskLevel}
-
-**Recomendación para v${version + 1}:**
-1. ${recommendation1}
-2. ${recommendation2}
-3. ${recommendation3}
-
-**Archivos Relacionados:**
-${relatedFiles.map(f => `- \`${f.path}\` - ${f.description}`).join('\n')}
-
-**Acceptance Criteria Afectados:**
-${affectedACs.map(ac => `- ${ac.id}: ${ac.impact}`).join('\n')}
-
----
-
-No hay más pendientes documentados para esta sesión.`
-})
-```
-
-### Step 4: Update Summary
-
-```typescript
-await Edit({
-  file_path: `${sessionPath}/pendings.md`,
-  old_string: `**Total Pendientes:** ${currentCount}
-**Prioridad Alta:** ${highCount}
-**Prioridad Media:** ${medCount}
-**Prioridad Baja:** ${lowCount}`,
-  new_string: `**Total Pendientes:** ${currentCount + 1}
-**Prioridad Alta:** ${newHighCount}
-**Prioridad Media:** ${newMedCount}
-**Prioridad Baja:** ${newLowCount}`
-})
-
-// Update status
-await Edit({
-  file_path: `${sessionPath}/pendings.md`,
-  old_string: "**Status:** Sin pendientes",
-  new_string: "**Status:** Con pendientes"
-})
-```
-
-### Step 5: Update Context
-
-```typescript
-await Edit({
-  file_path: `${sessionPath}/context.md`,
-  // Add note about new pending
-  new_content: `
----
-
-### [YYYY-MM-DD HH:MM] - task:pending
-
-**Estado:** ⚠️ Pendiente Documentado
-
-**Pendiente Agregado:** P${pendingCount} - ${pendingTitle}
-**Prioridad:** ${priority}
-**Categoría:** ${category}
-
-**Resumen:**
-${description}
-
-**Razón:**
-${mainReason}
-
-**Impacto:**
-${impactSummary}
-
-**Notas:**
-- Documentado en pendings.md
-- Será abordado en v${version + 1}
-`
-})
-```
-
----
-
-## Pending Item Template
-
-```markdown
-### P[N]: [Título del Pendiente]
-
-**Detectado por:** [agent-name]
-**Fecha:** YYYY-MM-DD
-**Prioridad:** Alta / Media / Baja
-**Categoría:** Feature / Bug / Refactor / Performance / Security / UX / Documentation
-
-**Descripción:**
-[Descripción detallada de qué quedó sin resolver]
-
-**Razón para Postergar:**
-- [ ] Tiempo insuficiente
-- [ ] Fuera del alcance actual
-- [ ] Requiere decisión de producto
-- [ ] Dependencia externa
-- [ ] Complejidad técnica alta
-- [ ] Otro: [especificar]
-
-**Impacto de No Resolverlo:**
-- Funcionalidad afectada: [descripción]
-- Usuarios afectados: [quiénes]
-- Riesgo: [bajo/medio/alto]
-
-**Recomendación para v[X+1]:**
-1. [Paso recomendado 1]
-2. [Paso recomendado 2]
-3. [Paso recomendado 3]
-
-**Archivos Relacionados:**
-- `path/to/file1.ts` - [descripción]
-- `path/to/file2.tsx` - [descripción]
-
-**Acceptance Criteria Afectados:**
-- AC[X]: [descripción de cómo afecta]
-```
-
----
-
-## Output Format
-
-```markdown
-## Pending Item Documented
-
-**Session:** `.claude/sessions/YYYY-MM-DD-feature-name-v1/`
-**Pending ID:** P[N]
-**Title:** [Pending Title]
-
-### Summary
-- **Priority:** [Alta/Media/Baja]
-- **Category:** [Category]
-- **Reason:** [Main reason for deferring]
-
-### Impact
-- **Affected:** [What's affected]
-- **Risk:** [Risk level]
-
-### For Next Version
-When creating v2, the PM and Architect will:
-1. Read this pendings.md
-2. Include this item in v2 requirements
-3. Plan appropriate solution
-
-### File Updated
-- `pendings.md` - Pending P[N] added
-- `context.md` - Entry added
-```
-
----
-
-## Best Practices for Pending Documentation
-
-### DO:
-- Be specific about what's pending
-- Explain WHY it's being deferred
-- Provide clear recommendations
-- List affected files and ACs
-- Estimate impact honestly
-
-### DON'T:
-- Use vague descriptions
-- Skip the impact assessment
-- Forget to update summary counts
-- Leave without recommendations
-- Document trivial items as pendings
-
----
-
-## When to Use This Command
-
-**Use task:pending when:**
-- Feature is partially complete but time-boxed
-- Edge case discovered but out of scope
-- Performance optimization identified but not critical
-- UX improvement suggested but not blocking
-- Technical debt found during implementation
-
-**DON'T use for:**
-- Bugs that block the feature (fix now)
-- Core functionality missing (expand scope)
-- Security vulnerabilities (fix immediately)
-- Items that should be separate features (create new session)
-
----
-
-**Now document the pending item for the session described above.**