@atlashub/smartstack-cli 2.7.2 → 2.7.4

package/templates/skills/apex/steps/step-01-analyze.md

@@ -1,263 +0,0 @@
----
-name: step-01-analyze
-description: Pure context gathering - explore codebase to understand WHAT EXISTS
-next_step: steps/step-02-plan.md
----
-
-# Step 1: Analyze (Context Gathering)
-
-## MANDATORY EXECUTION RULES:
-
-- NEVER plan or design solutions - that's step 2
-- NEVER create todos or implementation tasks
-- NEVER decide HOW to implement anything
-- ALWAYS focus on discovering WHAT EXISTS
-- ALWAYS report findings with file paths and line numbers
-- YOU ARE AN EXPLORER, not a planner
-- FORBIDDEN to suggest implementations or approaches
-
-## YOUR TASK:
-
-Gather ALL relevant context about WHAT CURRENTLY EXISTS in the codebase related to the task.
-
----
-
-<available_state>
-From step-00-init:
-
-| Variable | Description |
-|----------|-------------|
-| `{task_description}` | What to implement |
-| `{task_id}` | Kebab-case identifier |
-| `{auto_mode}` | Skip confirmations |
-| `{examine_mode}` | Auto-proceed to review |
-| `{save_mode}` | Save outputs to files |
-| `{test_mode}` | Include test steps |
-| `{economy_mode}` | No subagents, direct tools |
-| `{output_dir}` | Path to output (if save_mode) |
-</available_state>
-
----
-
-## EXECUTION SEQUENCE:
-
-### 1. Extract Search Keywords
-
-From the task description, identify:
-- **Domain terms**: auth, user, payment, etc.
-- **Technical terms**: API, route, component, etc.
-- **Action hints**: create, update, fix, add, etc.
-
-These keywords guide exploration - NOT planning.
-
-### 2. SmartStack MCP Context (if available)
-
-**Use MCP tools for SmartStack-specific context:**
-
-```
-mcp__smartstack__api_docs:
-  format: "markdown"
-  # Récupère la documentation API existante
-  # Identifie les endpoints, DTOs, et patterns utilisés
-```
-
-This provides:
-- Existing API endpoints and their structure
-- DTOs and request/response models
-- Controller patterns and conventions
-- NavRoute hierarchy
-
-### 3. Explore Codebase
-
-**If `{economy_mode}` = true:**
-
-Use direct tools only:
-1. Glob to find files: `**/*{keyword}*`
-2. Grep to search content in likely locations
-3. Read the most relevant 3-5 files
-4. Skip web research unless stuck
-
-**If `{economy_mode}` = false:**
-
-Launch parallel exploration agents in a SINGLE message:
-
-**Agent 1: Codebase Exploration** (`explore-codebase`)
-```
-Find existing code related to: {task_description}
-
-Report ONLY what exists:
-1. Files that contain related code (with paths and line numbers)
-2. Existing patterns used for similar features
-3. Utility functions that might be relevant
-4. How similar features are currently structured
-5. Test file locations and patterns
-
-DO NOT suggest what to build. Just report what's there.
-```
-
-**Agent 2: Documentation Research** (`explore-docs`)
-```
-Research documentation for libraries used in: {task_description}
-
-Find:
-1. How the relevant libraries/frameworks work
-2. API documentation for tools being used
-3. Best practices from official docs
-```
-
-**Agent 3: Web Research** (`websearch`)
-```
-Search for context about: {task_description}
-
-Find:
-1. How this is typically implemented
-2. Common patterns and approaches
-3. Known pitfalls or gotchas
-```
-
-### 4. Synthesize Findings
-
-Combine results into structured context:
-
-```markdown
-## Codebase Context
-
-### Related Files Found
-| File | Lines | Contains |
-|------|-------|----------|
-| `src/auth/login.ts` | 1-150 | Existing login implementation |
-| `src/utils/validate.ts` | 20-45 | Email validation helper |
-
-### Patterns Observed
-- **Route pattern**: Uses Next.js App Router with `route.ts`
-- **Validation**: Uses zod schemas in `schemas/` folder
-- **Error handling**: Throws custom ApiError classes
-
-### Utilities Available
-- `src/lib/auth.ts` - JWT sign/verify functions
-- `src/lib/db.ts` - Prisma client instance
-
-### Similar Implementations
-- `src/auth/login.ts:42` - Login flow (reference for patterns)
-
-### Test Patterns
-- Tests in `__tests__/` folders
-- Uses vitest with testing-library
-
-## Documentation Insights
-
-### Libraries Used
-- **jose**: JWT library - uses `SignJWT` class
-- **prisma**: ORM - uses `prisma.user.create()` pattern
-
-## Research Findings
-
-### Common Approaches
-- Registration: validate -> hash -> create -> issue token
-- Use httpOnly cookies for tokens
-```
-
-### 5. Infer Acceptance Criteria
-
-Based on task and context, infer success criteria:
-
-```markdown
-## Inferred Acceptance Criteria
-
-Based on "{task_description}" and existing patterns:
-
-- [ ] AC1: [specific measurable outcome]
-- [ ] AC2: [specific measurable outcome]
-- [ ] AC3: [specific measurable outcome]
-
-_These will be refined in the planning step._
-```
-
-### 6. Save Output (if save_mode)
-
-**If `{save_mode}` = true:**
-
-Write findings to `{output_dir}/01-analyze.md`:
-- Include all sections above
-- Add timestamp at the end
-- Update 00-context.md Progress table: 01-analyze -> Complete
-
-### 6b. Generate Context Digest (if save_mode)
-
-**If `{save_mode}` = true:**
-
-Generate a compact digest (max 50 lines) for inter-step context transfer.
-Use the template from `_resources/context-digest-template.md`.
-
-```markdown
-## Context Digest — step-01-analyze
-
-### Changes
-- N/A (analysis only)
-
-### Decisions
-- {key architectural or approach decisions from analysis}
-
-### Findings
-- {most important files found with paths}
-- {patterns identified, utilities available}
-
-### State
-- {acceptance_criteria}: [inferred list]
-- Files analyzed: {count}
-
-### Blockers
-- {open questions or ambiguities}
-
-### Next
-- Step-02 should focus on: {key areas for planning}
-```
-
-Write digest to `{output_dir}/01-analyze-digest.md`
-
-**Purpose:** Step-02 reads ONLY this digest (not the full 01-analyze.md) to minimize token usage.
-Exception: If `{resume_task}` is set, read the full output instead.
-
-### 7. Present Context Summary
-
-```
-**Context Gathering Complete**
-
-**Files analyzed:** {count}
-**Patterns identified:** {count}
-**Utilities found:** {count}
-
-**Key findings:**
-- {summary of relevant files}
-- {patterns that will guide implementation}
-
--> Proceeding to planning phase...
-```
-
-**Always proceed directly to step-02-plan.md**
-
----
-
-## SUCCESS METRICS:
-
-- Related files identified with paths and line numbers
-- Existing patterns documented with specific examples
-- Available utilities noted
-- Dependencies listed
-- Acceptance criteria inferred
-- NO planning or implementation decisions made
-
-## FAILURE MODES:
-
-- Starting to plan or design (that's step 2!)
-- Suggesting implementations or approaches
-- Missing obvious related files
-- Not documenting patterns with file:line references
-- Launching agents sequentially instead of parallel
-- Using subagents when economy_mode is true
-
----
-
-## NEXT STEP:
-
-Always proceed directly to `./step-02-plan.md` after presenting context summary.

package/templates/skills/apex/steps/step-02-plan.md

@@ -1,255 +0,0 @@
----
-name: step-02-plan
-description: Strategic planning - create detailed file-by-file implementation strategy
-prev_step: steps/step-01-analyze.md
-next_step: steps/step-03-execute.md
----
-
-# Step 2: Plan (Strategic Design)
-
-## MANDATORY EXECUTION RULES:
-
-- NEVER start implementing - that's step 3
-- NEVER write or modify code in this step
-- ALWAYS structure plan by FILE, not by feature
-- ALWAYS include specific line numbers from analysis
-- ALWAYS map acceptance criteria to file changes
-- YOU ARE A PLANNER, not an implementer
-- FORBIDDEN to use Edit, Write, or Bash tools
-
-## YOUR TASK:
-
-Transform analysis findings into a comprehensive, executable, file-by-file implementation plan.
-
----
-
-<available_state>
-From previous steps:
-
-| Variable | Description |
-|----------|-------------|
-| `{task_description}` | What to implement |
-| `{task_id}` | Kebab-case identifier |
-| `{acceptance_criteria}` | Success criteria from step-01 |
-| `{auto_mode}` | Skip confirmations |
-| `{save_mode}` | Save outputs to files |
-| `{output_dir}` | Path to output (if save_mode) |
-| Files found | From step-01 codebase exploration |
-| Patterns | From step-01 pattern analysis |
-| Utilities | From step-01 utility discovery |
-</available_state>
-
----
-
-## EXECUTION SEQUENCE:
-
-### 1. ULTRA THINK: Design Complete Strategy
-
-**CRITICAL: Think through ENTIRE implementation before writing any plan.**
-
-Mental simulation:
-- Walk through the implementation step by step
-- Identify all files that need changes
-- Determine logical order (dependencies first)
-- Consider edge cases and error handling
-- Plan test coverage
-
-### 2. Clarify Ambiguities
-
-**If `{auto_mode}` = true:**
-Use recommended option for any ambiguity, proceed automatically.
-
-**If `{auto_mode}` = false AND multiple valid approaches exist:**
-
-```yaml
-questions:
-  - header: "Approach"
-    question: "Multiple approaches are possible. Which should we use?"
-    options:
-      - label: "Approach A (Recommended)"
-        description: "Description and tradeoffs of A"
-      - label: "Approach B"
-        description: "Description and tradeoffs of B"
-      - label: "Approach C"
-        description: "Description and tradeoffs of C"
-    multiSelect: false
-```
-
-### 3. Create Detailed Plan
-
-**Structure by FILE, not by feature:**
-
-```markdown
-## Implementation Plan: {task_description}
-
-### Overview
-[1-2 sentences: High-level strategy and approach]
-
-### Prerequisites
-- [ ] Prerequisite 1 (if any)
-- [ ] Prerequisite 2 (if any)
-
----
-
-### File Changes
-
-#### `src/path/file1.ts`
-- Add `functionName` that handles X
-- Extract logic from Y (follow pattern in `example.ts:45`)
-- Handle error case: [specific scenario]
-- Consider: [edge case or important context]
-
-#### `src/path/file2.ts`
-- Update imports to include new module
-- Call `functionName` in existing flow at line ~42
-- Update types: Add `NewType` interface
-
-#### `src/path/file3.ts` (NEW FILE)
-- Create utility for Z
-- Export: `utilityFunction`, `HelperType`
-- Pattern: Follow `similar-util.ts` structure
-
----
-
-### Testing Strategy
-
-**New tests:**
-- `src/path/file1.test.ts` - Test functionName with:
-  - Happy path
-  - Error case
-  - Edge case
-
-**Update existing:**
-- `src/path/existing.test.ts` - Add test for new flow
-
----
-
-### Acceptance Criteria Mapping
-- [ ] AC1: Satisfied by changes in `file1.ts`
-- [ ] AC2: Satisfied by changes in `file2.ts`
-
----
-
-### Risks & Considerations
-- Risk 1: [potential issue and mitigation]
-```
-
-### 4. Verify Plan Completeness
-
-Checklist:
-- [ ] All files identified - nothing missing
-- [ ] Logical order - dependencies handled first
-- [ ] Clear actions - every step specific and actionable
-- [ ] Test coverage - all paths have test strategy
-- [ ] In scope - no scope creep
-- [ ] AC mapped - every criterion has implementation
-
-### 5. Save Plan (if save_mode)
-
-**If `{save_mode}` = true:**
-
-Write plan to `{output_dir}/02-plan.md`:
-- Include full plan above
-- Add timestamp
-- Update 00-context.md Progress table: 02-plan -> Complete
-
-### 5b. Generate Context Digest (if save_mode)
-
-**If `{save_mode}` = true:**
-
-Generate a compact digest (max 50 lines) for inter-step context transfer.
-Use the template from `_resources/context-digest-template.md`.
-
-```markdown
-## Context Digest — step-02-plan
-
-### Changes
-- {files planned for modification with summary}
-
-### Decisions
-- {approach chosen and why}
-- {key design decisions}
-
-### Findings
-- {risks identified}
-- {dependencies between files}
-
-### State
-- Plan approved: {yes/no}
-- Files to modify: {count}
-- New files: {count}
-
-### Blockers
-- {any user questions pending}
-
-### Next
-- Step-03 should implement files in this order: {ordered list}
-```
-
-Write digest to `{output_dir}/02-plan-digest.md`
-
-**Purpose:** Step-03 reads ONLY this digest + the plan structure (not full analysis) to minimize token usage.
-Exception: If `{resume_task}` is set, read the full outputs instead.
-
-### 6. Present Plan for Approval
-
-```
-**Implementation Plan Ready**
-
-**Overview:** [1 sentence summary]
-
-**Files to modify:** {count} files
-**New files:** {count} files
-**Tests:** {count} test files
-
-**Estimated changes:**
-- `file1.ts` - Major changes (add function, handle errors)
-- `file2.ts` - Minor changes (imports, single call)
-- `file1.test.ts` - New test file
-```
-
-**If `{auto_mode}` = true:**
-Skip confirmation, proceed directly to execution.
-
-**If `{auto_mode}` = false:**
-
-```yaml
-questions:
-  - header: "Plan"
-    question: "Review the implementation plan. Ready to proceed?"
-    options:
-      - label: "Approve and execute (Recommended)"
-        description: "Plan looks good, start implementation"
-      - label: "Adjust plan"
-        description: "I want to modify specific parts"
-      - label: "Ask questions"
-        description: "I have questions about the plan"
-      - label: "Start over"
-        description: "Revise the entire plan"
-    multiSelect: false
-```
-
----
-
-## SUCCESS METRICS:
-
-- Complete file-by-file plan created
-- Logical dependency order established
-- All acceptance criteria mapped to changes
-- Test strategy defined
-- User approved plan (or auto-approved)
-- NO code written or modified
-
-## FAILURE MODES:
-
-- Organizing by feature instead of file
-- Vague actions like "add feature" or "fix issue"
-- Missing test strategy
-- Not mapping to acceptance criteria
-- Starting to write code (that's step 3!)
-
----
-
-## NEXT STEP:
-
-After user approves (or auto-proceed), load `./step-03-execute.md`