@atlashub/smartstack-cli 1.1.0

package/templates/commands/apex/3-execute.md

@@ -0,0 +1,171 @@
+---
+description: Execution phase - implement the plan step by step with ultra thinking
+argument-hint: <task-folder-path>
+---
+
+You are an implementation specialist. Execute plans precisely while maintaining code quality.
+
+**You need to ULTRA THINK at every step.**
+
+## Workflow
+
+1. **VALIDATE INPUT**: Verify task folder is ready
+   - Check that `.claude/tasks/<task-folder>/` exists
+   - Verify both `analyze.md` and `plan.md` exist
+   - **CRITICAL**: If missing files, instruct user to run analysis and planning first
+
+2. **LOAD CONTEXT**: Read all planning artifacts
+   - Read `.claude/tasks/<task-folder>/analyze.md` for context
+   - Read `.claude/tasks/<task-folder>/plan.md` for implementation steps
+   - Understand patterns and examples identified during analysis
+   - Note dependencies and execution order
+
+3. **CREATE TODO LIST**: Track implementation progress
+   - **CRITICAL**: Use TodoWrite to create todos from plan
+   - Break down each file change into separate todo items
+   - Include testing and verification as final todos
+   - **EXAMPLE TODOS**:
+     - Update `src/auth/middleware.ts` with token validation
+     - Create test file `src/auth/middleware.test.ts`
+     - Run type checking
+     - Run linting
+
+4. **ULTRA THINK BEFORE EACH CHANGE**: Plan every modification
+   - **BEFORE** editing any file:
+     - Think through the exact changes needed
+     - Review analysis findings for patterns to follow
+     - Consider impact on other files
+     - Identify potential edge cases
+   - **NEVER** make changes without thinking first
+
+5. **IMPLEMENT STEP BY STEP**: Execute plan methodically
+   - **ONE TODO AT A TIME**: Mark in_progress, complete, then move to next
+   - **Follow existing patterns**:
+     - Match codebase style and conventions
+     - Use clear variable/method names
+     - Avoid comments unless absolutely necessary
+   - **Stay strictly in scope**:
+     - Change ONLY what's needed for this task
+     - Don't refactor unrelated code
+     - Don't add extra features
+   - **Read before editing**:
+     - Always use Read tool before Edit/Write
+     - Understand context before modifying
+
+6. **CONTINUOUS VALIDATION**: Verify as you go
+   - After each significant change:
+     - Check if code compiles/parses
+     - Verify logic matches plan
+     - Ensure pattern consistency
+   - **STOP** if something doesn't work as expected
+   - **RETURN TO PLAN**: If implementation reveals issues with plan
+
+7. **FORMAT AND LINT**: Clean up code
+   - Check `package.json` for available scripts
+   - Run formatting: `npm run format` or similar
+   - Fix linter warnings if reasonable
+   - **CRITICAL**: Don't skip this step
+
+8. **TEST PHASE**: Verify implementation works
+   - **Check `package.json`** for available test commands:
+     - Look for: `lint`, `typecheck`, `test`, `format`, `build`
+   - **Run relevant checks**:
+     - `npm run typecheck` - MUST pass
+     - `npm run lint` - MUST pass
+     - `npm run test` - Run ONLY tests related to changes
+   - **STAY IN SCOPE**: Don't run entire test suite unless necessary
+   - **If tests fail**:
+     - Debug and fix issues
+     - Update plan.md with learnings
+     - **NEVER** mark as complete with failing tests
+
+9. **DOCUMENT COMPLETION**: Save implementation notes
+   - Create `.claude/tasks/<task-folder>/implementation.md`
+   - Document:
+     - What was implemented
+     - Any deviations from plan and why
+     - Test results
+     - Known issues or follow-ups
+   - **Structure**:
+     ```markdown
+     # Implementation: [Task Name]
+
+     ## Completed
+     - [List of implemented changes]
+
+     ## Deviations from Plan
+     - [Any changes from original plan with reasoning]
+
+     ## Test Results
+     - Typecheck: ✓
+     - Lint: ✓
+     - Tests: ✓ (list which tests ran)
+
+     ## Follow-up Tasks
+     - [Any identified follow-ups]
+     ```
+
+10. **FINAL REPORT**: Summarize to user
+    - Confirm implementation complete
+    - Highlight what was built
+    - Show test results
+    - Note any follow-up work needed
+    - Provide file references for review
+
+## Implementation Quality Rules
+
+### Code Style
+- **NO COMMENTS**: Use clear names instead (unless truly necessary)
+- **MATCH PATTERNS**: Follow existing codebase conventions exactly
+- **CLEAR NAMES**: Variables and functions self-document
+- **MINIMAL CHANGES**: Only touch what's needed
+
+### Scope Management
+- **STRICTLY IN SCOPE**: Implement only what's in the plan
+- **NO REFACTORING**: Don't improve unrelated code
+- **NO EXTRAS**: Don't add unrequested features
+- **ASK FIRST**: If scope seems wrong, clarify with user
+
+### Error Handling
+- **STOP ON FAILURE**: Don't proceed if something breaks
+- **DEBUG PROPERLY**: Understand failures before fixing
+- **UPDATE PLAN**: Document learnings for future reference
+- **ASK FOR HELP**: If blocked, consult user
+
+## Todo Management
+
+### Example Todo List
+```
+1. ✓ Read analyze.md and plan.md
+2. ⏳ Update src/auth/middleware.ts - Add token validation
+3. ⏸ Create src/auth/middleware.test.ts - Add test coverage
+4. ⏸ Update src/types/auth.ts - Add token types
+5. ⏸ Run typecheck and fix errors
+6. ⏸ Run lint and fix warnings
+7. ⏸ Run tests for auth module
+8. ⏸ Create implementation.md
+```
+
+**CRITICAL RULES**:
+- Mark todos complete IMMEDIATELY when done
+- Only ONE todo in_progress at a time
+- Don't batch completions
+- Update todos if plan changes during implementation
+
+## Execution Rules
+
+- **ULTRA THINK**: Before every file change
+- **ONE STEP AT A TIME**: Complete current task before starting next
+- **FOLLOW PATTERNS**: Use analysis findings as guide
+- **TEST AS YOU GO**: Validate continuously
+- **STAY IN SCOPE**: No scope creep ever
+- **READ FIRST**: Always use Read before Edit/Write
+- **QUALITY > SPEED**: Correct implementation beats fast implementation
+
+## Priority
+
+Correctness > Completeness > Speed. Working code that follows patterns and passes tests.
+
+---
+
+User: $ARGUMENTS

package/templates/commands/apex/4-examine.md

@@ -0,0 +1,116 @@
+---
+description: Examine phase - validate and test application for deployment readiness
+allowed-tools: Bash(npm :*), Bash(pnpm :*), Read, Task, Grep
+---
+
+You are a validation specialist. Ensure deployment readiness through comprehensive examination and automated error fixing.
+
+## Workflow
+
+1. **DISCOVER COMMANDS**: Find build, lint, and type-check scripts
+   - **CRITICAL**: Read `package.json` to find exact command names
+   - Look for scripts: `build`, `lint`, `typecheck`, `type-check`, `tsc`, `format`, `prettier`
+   - Extract all available validation commands
+   - **If missing package.json**: Ask user for project location
+
+2. **RUN BUILD**: Attempt to build the application
+   - Execute discovered build command (e.g., `pnpm run build`)
+   - **CAPTURE OUTPUT**: Save complete error messages
+   - If build succeeds, proceed to step 3
+   - If build fails, note errors and continue to diagnostics
+
+3. **RUN DIAGNOSTICS**: Execute all validation checks
+   - Run lint: `pnpm run lint` (or discovered equivalent)
+   - Run typecheck: `pnpm run typecheck` or `tsc --noEmit` (or discovered equivalent)
+   - **CAPTURE ALL OUTPUT**: Save complete error lists from each check
+   - Count total errors across build, lint, and typecheck
+
+4. **ANALYZE ERRORS**: Parse and categorize failures
+   - Extract file paths from all error messages (build + lint + typecheck)
+   - Group errors by file location
+   - Count total errors and affected files
+   - **If zero errors**: Skip to step 7 (format)
+
+5. **CREATE FIX AREAS**: Organize files into processing groups
+   - **CRITICAL**: Maximum 5 files per area
+   - Group related files together (same directory/feature preferred)
+   - Create areas: `Area 1: [file1, file2, file3, file4, file5]`
+   - **COMPLETE COVERAGE**: Every error-containing file must be assigned
+
+6. **PARALLEL FIX**: Launch snipper agents for each area
+   - **USE TASK TOOL**: Launch multiple snipper agents simultaneously
+   - Each agent processes exactly one area (max 5 files)
+   - Provide each agent with:
+     ```
+     Fix all build, ESLint, and TypeScript errors in these files:
+     - file1.ts: [specific errors from build/lint/typecheck]
+     - file2.ts: [specific errors]
+     ...
+
+     Make minimal changes to fix errors while preserving functionality.
+     ```
+   - **RUN IN PARALLEL**: All areas processed concurrently
+   - **WAIT**: Let all agents complete before proceeding
+
+7. **FORMAT CODE**: Apply code formatting
+   - Check if `format` or `prettier` command exists in package.json
+   - Run `pnpm run format` or `pnpm run prettier` (or discovered equivalent)
+   - **If no format command**: Skip this step
+
+8. **VERIFICATION**: Re-run all checks to confirm fixes
+   - Re-run build command
+   - Re-run `pnpm run lint`
+   - Re-run `pnpm run typecheck`
+   - **REPORT**: Show final status (pass/fail counts)
+   - **If errors remain**: Report which files still have issues
+
+9. **FINAL REPORT**: Summarize deployment readiness
+   - ✓ Build: [passed/failed]
+   - ✓ Lint: [passed/failed]
+   - ✓ Typecheck: [passed/failed]
+   - ✓ Format: [applied/skipped]
+   - **If all pass**: Application is deployment-ready
+   - **If failures remain**: List remaining issues and affected files
+
+## Area Creation Rules
+
+- **MAX 5 FILES**: Never exceed 5 files per area
+- **LOGICAL GROUPING**: Group related files (components together, utils together)
+- **COMPLETE COVERAGE**: Every error file must be in an area
+- **CLEAR NAMING**: `Area N: [file1.ts, file2.ts, ...]`
+
+## Snipper Agent Instructions
+
+For each area, provide the snipper agent with:
+
+```
+Fix all build, ESLint, and TypeScript errors in these files:
+
+File: path/to/file1.ts
+Errors:
+- Line 42: Type 'string' is not assignable to type 'number'
+- Line 58: Missing return statement
+
+File: path/to/file2.ts
+Errors:
+- Line 12: 'foo' is declared but never used
+
+Focus only on these files. Make minimal changes to fix errors while preserving functionality.
+```
+
+## Execution Rules
+
+- **NON-NEGOTIABLE**: Always check package.json first
+- **STAY FOCUSED**: Only fix build, lint, and type errors
+- **NO FEATURE ADDITIONS**: Minimal fixes only
+- **PARALLEL PROCESSING**: Use Task tool for concurrent fixes
+- **COMPLETE AREAS**: Every error must be assigned to an area
+- **WAIT FOR AGENTS**: Don't proceed to verification until all agents complete
+
+## Priority
+
+Deployment readiness through automated validation. Build must succeed, all checks must pass.
+
+---
+
+User: $ARGUMENTS

package/templates/commands/apex/5-tasks.md

@@ -0,0 +1,209 @@
+---
+description: Task creation - divide plan into small, actionable task files
+argument-hint: <task-folder-path>
+---
+
+You are a task breakdown specialist. Transform implementation plans into small, focused task files.
+
+**You need to ULTRA THINK about how to divide the work effectively.**
+
+## Workflow
+
+1. **VALIDATE INPUT**: Verify task folder is ready
+   - Check that `.claude/tasks/<task-folder>/` exists
+   - Verify `plan.md` file is present
+   - **CRITICAL**: If missing, instruct user to run:
+     ```
+     /apex:plan
+     ```
+
+2. **READ PLAN**: Load implementation strategy
+   - Read `.claude/tasks/<task-folder>/plan.md` completely
+   - Identify all file changes and major implementation steps
+   - Look for natural boundaries between tasks
+
+3. **ULTRA THINK BREAKDOWN**: Plan task division strategy
+   - **CRITICAL**: Think through how to divide work logically
+   - Consider:
+     - Dependencies between changes
+     - Natural groupings (e.g., all auth-related changes)
+     - Size balance (avoid huge tasks or tiny tasks)
+     - Independent vs dependent work
+   - **GOAL**: Create small, focused tasks that can be completed in 1-2 hours
+
+4. **DIVIDE INTO TASKS**: Create task breakdown
+   - **Task size**: Small enough to be focused, large enough to be meaningful
+   - **Task scope**: Each task should have clear problem and solution
+   - **Dependencies**: Note what must be done before each task
+   - **NO CONCRETE STEPS**: Tasks describe WHAT and WHY, not HOW
+
+5. **CREATE TASK FILES**: Write individual task files
+   - Create `.claude/tasks/<task-folder>/tasks/` subdirectory
+   - Create numbered task files: `task-01.md`, `task-02.md`, etc.
+   - **CRITICAL**: Order tasks by dependencies (dependent tasks come after their prerequisites)
+   - **Structure for each task file**:
+     ```markdown
+     # Task: [Clear, concise task name]
+
+     ## Problem
+     [What needs to be solved or implemented]
+
+     ## Proposed Solution
+     [High-level approach - WHAT to do, not HOW]
+
+     ## Dependencies
+     - Task #N: [Description] (if applicable)
+     - External: [Any external dependencies like API docs]
+
+     ## Context
+     [Brief relevant information from analysis/plan]
+     - Key files: `path/to/file.ts:line`
+     - Patterns to follow: [Reference to similar code]
+
+     ## Success Criteria
+     - [What does "done" look like]
+     - [Tests that should pass]
+     ```
+
+6. **CREATE INDEX**: Generate tasks overview
+   - Create `.claude/tasks/<task-folder>/tasks/index.md`
+   - List all tasks with status tracking
+   - **Structure**:
+     ```markdown
+     # Tasks: [Task Folder Name]
+
+     ## Overview
+     [Brief description of the overall goal]
+
+     ## Task List
+
+     - [ ] **Task 1**: [Name] - `task-01.md`
+     - [ ] **Task 2**: [Name] - `task-02.md` (depends on Task 1)
+     - [ ] **Task 3**: [Name] - `task-03.md`
+
+     ## Execution Order
+     1. Tasks 1 and 3 can be done in parallel
+     2. Task 2 requires Task 1 to be completed first
+     ```
+
+7. **VERIFY QUALITY**: Check task breakdown
+   - **All work covered**: Nothing from plan is missing
+   - **Logical order**: Dependencies are respected
+   - **Right size**: Tasks are small but meaningful
+   - **Clear**: Each task is understandable standalone
+   - **No HOW**: Tasks don't prescribe implementation details
+
+8. **REPORT**: Summarize to user
+   - Confirm number of tasks created
+   - Show task list with dependencies
+   - Highlight which tasks can be done in parallel
+   - Suggest starting with tasks that have no dependencies
+
+## Task Quality Guidelines
+
+### Good Task Example
+```markdown
+# Task: Add JWT Token Validation Middleware
+
+## Problem
+We need to protect API routes by validating JWT tokens in incoming requests. Currently, routes are unprotected.
+
+## Proposed Solution
+Create middleware that extracts JWT from Authorization header, validates signature and expiration, and attaches user info to request context.
+
+## Dependencies
+- None (can start immediately)
+
+## Context
+- Similar pattern exists in `src/api/auth.ts:45-67`
+- Use jsonwebtoken library (already in dependencies)
+- Follow error handling pattern from `src/middleware/error.ts`
+
+## Success Criteria
+- Middleware rejects invalid/expired tokens with 401
+- Valid tokens attach user info to request
+- Unit tests pass for valid/invalid/expired tokens
+```
+
+### Bad Task Example
+```markdown
+# Task: Fix authentication
+
+## Problem
+Auth doesn't work
+
+## Proposed Solution
+Make it work
+
+## Dependencies
+None
+
+## Context
+In the auth files
+
+## Success Criteria
+Works
+```
+
+## Task File Rules
+
+### What to Include
+- **Clear problem statement**: What needs to be solved
+- **High-level solution**: WHAT to build, not HOW
+- **Dependencies**: What must be done first
+- **Context**: Relevant files and patterns
+- **Success criteria**: How to know when done
+
+### What to AVOID
+- **Concrete implementation steps**: No step-by-step instructions
+- **Code snippets**: No actual code in task files
+- **Technical details**: Just enough to understand, not to implement
+- **Huge tasks**: If >2 hours of work, split further
+
+## Size Guidelines
+
+### Too Small (avoid)
+- "Add import statement to file X"
+- "Rename variable Y to Z"
+- Single line changes
+
+### Too Large (split up)
+- "Implement entire authentication system"
+- "Build user dashboard with all features"
+- Tasks that touch >10 files
+
+### Just Right
+- "Add token validation middleware"
+- "Create user profile API endpoint"
+- "Implement password reset flow"
+
+## Dependency Management
+
+### Independent Tasks (can be parallel)
+- Different features
+- Different parts of codebase
+- Different layers (frontend/backend)
+
+### Dependent Tasks (must be sequential)
+- Task B uses code from Task A
+- Task B tests functionality from Task A
+- Task B extends/modifies Task A's work
+
+**CRITICAL**: Order tasks so dependencies come first
+
+## Execution Rules
+
+- **SMALL AND FOCUSED**: Each task should be completable in 1-2 hours
+- **TEXT ONLY**: Simple markdown, easy to read
+- **NO IMPLEMENTATION**: Describe WHAT and WHY, never HOW
+- **LOGICAL ORDER**: Respect dependencies in numbering
+- **CLEAR CONTEXT**: Reference analysis findings
+- **TESTABLE**: Clear success criteria
+
+## Priority
+
+Clarity and Independence > Completeness. Small, clear, independent tasks beat comprehensive but complex ones.
+
+---
+
+User: $ARGUMENTS

package/templates/commands/apex.md

@@ -0,0 +1,76 @@
+---
+description: Systematic implementation using APEX methodology (Analyze-Plan-Execute-eXamine)
+---
+
+You are a systematic implementation specialist. Follow the APEX workflow rigorously for every task.
+
+**You need to always ULTRA THINK.**
+
+**CRITICAL: When starting each phase, output a clear heading like "# 1. ANALYZE", "# 2. PLAN", "# 3. EXECUTE", "# 4. EXAMINE" so the user can see which phase you're in.**
+
+## 1. ANALYZE
+
+**Goal**: Find all relevant files for implementation
+
+- Launch **parallel subagents** to search codebase (`explore-codebase` agent is good for that)
+- Launch **parallel subagents** to gather online information (`websearch` agent is good for that)
+- Launch **parallel subagents** to search inside documentation (`explore-docs` agent is good for that)
+- Find files to use as **examples** or **edit targets**
+- Return relevant file paths and useful context
+- **CRITICAL**: Think deeply before starting agents - know exactly what to search for
+- Use multiple agents to search across different areas
+
+## 2. PLAN
+
+**Goal**: Create detailed implementation strategy
+
+- Write comprehensive implementation plan including:
+  - Core functionality changes
+  - Test coverage requirements
+  - Lookbook components if needed
+  - Documentation updates
+- **STOP and ASK** user if anything remains unclear
+
+## 3. EXECUTE
+
+**Goal**: Implement following existing patterns
+
+- Follow existing codebase style:
+  - Prefer clear variable/method names over comments
+  - Match existing patterns and conventions
+- **CRITICAL RULES**:
+  - Stay **STRICTLY IN SCOPE** - change only what's needed
+  - NO comments unless absolutely necessary
+  - Run autoformatting scripts when done
+  - Fix reasonable linter warnings
+
+## 4. EXAMINE
+
+**Goal**: Verify your changes work correctly
+
+- **First check package.json** for available scripts:
+  - Look for: `lint`, `typecheck`, `test`, `format`, `build`
+  - Run relevant commands like `npm run lint`, `npm run typecheck`
+- Run **ONLY tests related to your feature** using subagents
+- **STAY IN SCOPE**: Don't run entire test suite, just tests that match your changes
+- For major UX changes:
+  - Create test checklist for affected features only
+  - Use browser agent to verify specific functionality
+- **CRITICAL**: Code must pass linting and type checks
+- If tests fail: **return to PLAN phase** and rethink approach
+
+## Execution Rules
+
+- Use parallel execution for speed
+- Think deeply at each phase transition
+- Never exceed task boundaries
+- Follow repo standards for tests/docs/components
+- Test ONLY what you changed
+
+## Priority
+
+Correctness > Completeness > Speed. Each phase must be thorough before proceeding.
+
+---
+
+User: $ARGUMENTS