@atlashub/smartstack-cli 1.13.2 → 1.14.1

package/templates/skills/apex/steps/step-00-init.md

@@ -0,0 +1,203 @@
+---
+name: step-00-init
+description: Initialize APEX workflow - parse flags, detect continuation, setup state
+next_step: steps/step-01-analyze.md
+---
+
+# Step 0: Initialization
+
+## MANDATORY EXECUTION RULES:
+
+- NEVER skip flag parsing
+- ALWAYS parse ALL flags before any other action
+- ONLY check for resume if {resume_task} is set
+- YOU ARE AN INITIALIZER, not an executor
+- FORBIDDEN to load step-01 until init is complete
+
+## YOUR TASK:
+
+Initialize the APEX workflow by parsing flags, detecting continuation state, and setting up the execution environment.
+
+---
+
+<defaults>
+## Default Configuration
+
+```yaml
+auto_mode: false      # -a: Skip confirmations
+examine_mode: false   # -x: Auto-proceed to adversarial review
+save_mode: false      # -s: Save outputs to .claude/output/apex/
+test_mode: false      # -t: Include test creation and runner steps
+economy_mode: false   # -e: No subagents, save tokens
+```
+</defaults>
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Parse Flags and Input
+
+**Step 1: Load defaults from config above**
+
+```
+{auto_mode}    = false
+{examine_mode} = false
+{save_mode}    = false
+{test_mode}    = false
+{economy_mode} = false
+```
+
+**Step 2: Parse user input and override defaults:**
+
+```
+Enable flags (lowercase - turn ON):
+  -a or --auto     -> {auto_mode} = true
+  -x or --examine  -> {examine_mode} = true
+  -s or --save     -> {save_mode} = true
+  -t or --test     -> {test_mode} = true
+  -e or --economy  -> {economy_mode} = true
+
+Disable flags (UPPERCASE - turn OFF):
+  -A or --no-auto         -> {auto_mode} = false
+  -X or --no-examine      -> {examine_mode} = false
+  -S or --no-save         -> {save_mode} = false
+  -T or --no-test         -> {test_mode} = false
+  -E or --no-economy      -> {economy_mode} = false
+
+Other:
+  -r or --resume   -> {resume_task} = <next argument>
+  -i or --interactive -> {interactive_mode} = true
+  Remainder        -> {task_description}
+```
+
+**Step 3: Generate feature_name and task_id:**
+
+```
+{feature_name} = kebab-case-description
+Example: "add user authentication" -> "add-user-authentication"
+
+{task_id} = NN-{feature_name}
+- Auto-detect next available number from .claude/output/apex/
+- Example: "01-add-user-authentication"
+```
+
+### 2. Check Resume Mode
+
+**ONLY execute if {resume_task} is set!**
+
+If `{resume_task}` is set:
+
+1. Search for matching task in `.claude/output/apex/`
+2. If found: Read `00-context.md` to restore state variables
+3. Find last completed step (look for "Status: Complete" markers)
+4. Load next incomplete step
+5. **STOP** - do not continue with fresh init
+
+If no match found: List available tasks and ask user to specify.
+
+### 3. Interactive Mode (if -i flag)
+
+If `{interactive_mode}` = true:
+
+```yaml
+questions:
+  - header: "Configure"
+    question: "Select flags to enable for this workflow:"
+    options:
+      - label: "Auto mode (-a)"
+        description: "Skip all confirmations, use recommended options"
+      - label: "Examine mode (-x)"
+        description: "Include adversarial code review at end"
+      - label: "Save mode (-s)"
+        description: "Save all outputs to .claude/output/apex/"
+      - label: "Test mode (-t)"
+        description: "Include test creation and runner steps"
+      - label: "Economy mode (-e)"
+        description: "No subagents, direct tools only (saves tokens)"
+    multiSelect: true
+```
+
+### 4. Create Output Structure (if save_mode)
+
+**If `{save_mode}` = true:**
+
+1. Create directory: `.claude/output/apex/{task_id}/`
+
+2. Write `00-context.md`:
+
+```markdown
+# APEX Task: {task_id}
+
+**Created:** {timestamp}
+**Task:** {task_description}
+
+## Configuration
+
+| Flag | Value |
+|------|-------|
+| Auto mode | {auto_mode} |
+| Examine mode | {examine_mode} |
+| Save mode | {save_mode} |
+| Test mode | {test_mode} |
+| Economy mode | {economy_mode} |
+
+## User Request
+
+{original user input}
+
+## Acceptance Criteria
+
+_To be defined in step-01-analyze_
+
+## Progress
+
+| Step | Status |
+|------|--------|
+| 00-init | In Progress |
+| 01-analyze | Pending |
+| 02-plan | Pending |
+| 03-execute | Pending |
+| 04-validate | Pending |
+| 05-examine | {examine_mode ? "Pending" : "Skip"} |
+| 06-resolve | {examine_mode ? "Pending" : "Skip"} |
+| 07-tests | {test_mode ? "Pending" : "Skip"} |
+| 08-run-tests | {test_mode ? "Pending" : "Skip"} |
+```
+
+3. Mark 00-init as Complete in the Progress table
+
+### 5. Show Summary and Proceed
+
+**Always show COMPACT summary:**
+
+```
+APEX: {task_description}
+
+| Variable | Value |
+|----------|-------|
+| {task_id} | 01-kebab-name |
+| {auto_mode} | true/false |
+| {examine_mode} | true/false |
+| {save_mode} | true/false |
+| {test_mode} | true/false |
+| {economy_mode} | true/false |
+
+-> Analyzing...
+```
+
+**Then proceed directly to step-01-analyze.md**
+
+---
+
+## SUCCESS METRICS:
+
+- All flags correctly parsed
+- Output is COMPACT (one table, no verbose logs)
+- Variables shown with `{brackets}` notation
+- Proceeded to step-01 immediately after summary
+- Output folder created with 00-context.md (if save_mode)
+
+## NEXT STEP:
+
+After showing initialization summary, always proceed directly to `./step-01-analyze.md`

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

@@ -0,0 +1,210 @@
+---
+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. 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
+```
+
+### 3. 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
+```
+
+### 4. 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._
+```
+
+### 5. 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
+
+### 6. 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

@@ -0,0 +1,217 @@
+---
+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
+
+### 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`