@atlashub/smartstack-cli 1.13.2 → 1.14.1

package/templates/skills/apex/steps/step-06-resolve.md

@@ -0,0 +1,181 @@
+---
+name: step-06-resolve
+description: Resolve findings - interactively address review issues
+prev_step: steps/step-05-examine.md
+next_step: COMPLETE
+---
+
+# Step 6: Resolve Findings
+
+## MANDATORY EXECUTION RULES:
+
+- NEVER auto-fix Noise or Uncertain findings
+- NEVER skip validation after fixes
+- ALWAYS present resolution options to user (unless auto_mode)
+- ALWAYS validate after applying fixes
+- ALWAYS provide clear completion summary
+- YOU ARE A RESOLVER, addressing identified issues
+- FORBIDDEN to proceed with failing validation
+
+## YOUR TASK:
+
+Address adversarial review findings interactively - fix real issues, dismiss noise, discuss uncertain items.
+
+---
+
+<available_state>
+From previous steps:
+
+| Variable | Description |
+|----------|-------------|
+| `{task_description}` | What was implemented |
+| `{task_id}` | Kebab-case identifier |
+| `{auto_mode}` | Auto-fix Real findings |
+| `{save_mode}` | Save outputs to files |
+| `{output_dir}` | Path to output (if save_mode) |
+| Findings table | IDs, severity, validity |
+| Finding todos | For tracking |
+</available_state>
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Present Resolution Options
+
+**If `{auto_mode}` = true:**
+Auto-fix all "Real" findings, skip Noise/Uncertain.
+
+**If `{auto_mode}` = false:**
+
+```yaml
+questions:
+  - header: "Resolution"
+    question: "How would you like to handle these findings?"
+    options:
+      - label: "Auto-fix Real issues (Recommended)"
+        description: "Fix 'Real' findings, skip noise/uncertain"
+      - label: "Walk through each finding"
+        description: "Decide on each finding individually"
+      - label: "Fix only critical"
+        description: "Only fix CRITICAL/BLOCKING issues"
+      - label: "Skip all"
+        description: "Acknowledge but don't change"
+    multiSelect: false
+```
+
+### 2. Apply Fixes Based on Choice
+
+**Auto-fix Real:**
+1. Filter to Real findings only
+2. For each: Read file -> Apply fix -> Verify
+3. Log each fix
+
+**Walk through each:**
+For each finding in severity order:
+
+```yaml
+questions:
+  - header: "F1"
+    question: "How should we handle this finding?"
+    options:
+      - label: "Fix now (Recommended)"
+        description: "Apply the suggested fix"
+      - label: "Skip"
+        description: "Acknowledge but don't fix"
+      - label: "Discuss"
+        description: "Need more context"
+      - label: "Mark as noise"
+        description: "Not a real issue"
+    multiSelect: false
+```
+
+**Fix only critical:**
+1. Filter to CRITICAL/BLOCKING only
+2. Auto-fix those, skip others
+
+**Skip all:**
+1. Acknowledge findings
+2. If Critical/High exist, confirm user wants to proceed anyway
+
+### 3. Post-Resolution Validation
+
+After any fixes:
+
+```bash
+pnpm run typecheck && pnpm run lint
+```
+
+Both MUST pass.
+
+### 4. Resolution Summary
+
+```
+**Resolution Complete**
+
+**Fixed:** {count}
+- F1: Parameterized SQL query in auth.ts:42
+- F2: Added null check in handler.ts:78
+
+**Skipped:** {count}
+- F3: Complex function (uncertain)
+
+**Validation:** Pass
+```
+
+### 5. Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+Write to `{output_dir}/06-resolve.md`:
+- Resolution summary
+- Fixes applied
+- Timestamp
+- Update 00-context.md Progress table: 06-resolve -> Complete
+
+### 6. Completion Summary
+
+```
+**APEX Workflow Complete**
+
+**Task:** {task_description}
+
+**Implementation:**
+- Files modified: {count}
+- All checks passing: Yes
+
+**Review:**
+- Findings identified: {total}
+- Findings resolved: {fixed}
+- Findings skipped: {skipped}
+
+**Next Steps:**
+- [ ] Commit changes
+- [ ] Run full test suite
+- [ ] Deploy when ready
+```
+
+---
+
+## SUCCESS METRICS:
+
+- User chose resolution approach
+- All chosen fixes applied correctly
+- Validation passes after fixes
+- Clear summary of resolved/skipped
+- User understands next steps
+
+## FAILURE MODES:
+
+- Auto-fixing Noise or Uncertain findings
+- Not validating after fixes
+- No clear completion summary
+- Proceeding with failing validation
+
+---
+
+## NEXT STEP:
+
+Based on flags:
+- **If test_mode:** Load `./step-07-tests.md`
+- **Otherwise:** Workflow complete - show summary

package/templates/skills/apex/steps/step-07-tests.md

@@ -0,0 +1,206 @@
+---
+name: step-07-tests
+description: Test analysis and creation - identify gaps and write tests
+prev_step: steps/step-04-validate.md
+next_step: steps/step-08-run-tests.md
+---
+
+# Step 7: Tests (Analysis & Creation)
+
+## MANDATORY EXECUTION RULES:
+
+- NEVER skip test coverage analysis
+- NEVER write tests without reading existing patterns
+- ALWAYS identify untested code paths
+- ALWAYS follow existing test patterns
+- ALWAYS create meaningful assertions
+- YOU ARE A TEST ENGINEER, ensuring quality
+- FORBIDDEN to write redundant tests
+
+## YOUR TASK:
+
+Analyze test coverage for the implementation, identify gaps, and create comprehensive tests.
+
+---
+
+<available_state>
+From previous steps:
+
+| Variable | Description |
+|----------|-------------|
+| `{task_description}` | What was implemented |
+| `{task_id}` | Kebab-case identifier |
+| `{auto_mode}` | Skip confirmations |
+| `{save_mode}` | Save outputs to files |
+| `{economy_mode}` | No subagents, direct tools |
+| `{output_dir}` | Path to output (if save_mode) |
+| Files modified | From step-03 |
+</available_state>
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Analyze Existing Tests
+
+**If `{economy_mode}` = true:**
+
+Use direct tools:
+1. Glob for test files: `**/*.test.ts`, `**/*.spec.ts`
+2. Read 1-2 similar test files for patterns
+3. Identify test framework (jest, vitest, etc.)
+
+**If `{economy_mode}` = false:**
+
+Launch exploration agent:
+```
+Analyze test structure for: {task_description}
+
+Find:
+1. Test file naming conventions
+2. Test patterns used (describe/it, test())
+3. Mocking patterns
+4. Assertion style (expect, assert)
+5. Coverage of similar features
+```
+
+### 2. Identify Test Gaps
+
+For each modified file, determine:
+
+```markdown
+## Test Coverage Analysis
+
+### `src/auth/handler.ts`
+**Existing coverage:** 60%
+**New code coverage:** 0%
+
+**Untested paths:**
+- [ ] `validateToken` happy path
+- [ ] `validateToken` expired token error
+- [ ] `validateToken` invalid signature error
+
+### `src/api/auth/route.ts`
+**Existing coverage:** 80%
+**New code coverage:** 0%
+
+**Untested paths:**
+- [ ] POST endpoint with valid credentials
+- [ ] POST endpoint with invalid credentials
+```
+
+### 3. Plan Test Creation
+
+```markdown
+## Test Plan
+
+### New Test Files
+- `src/auth/__tests__/handler.test.ts`
+  - Test validateToken function
+  - 3 test cases planned
+
+### Update Existing Tests
+- `src/api/auth/__tests__/route.test.ts`
+  - Add integration tests for new endpoint
+  - 2 test cases planned
+
+### Test Cases Summary
+| File | Function | Test Case | Priority |
+|------|----------|-----------|----------|
+| handler.test.ts | validateToken | Valid token returns payload | High |
+| handler.test.ts | validateToken | Expired token throws error | High |
+| handler.test.ts | validateToken | Invalid signature throws | Medium |
+```
+
+### 4. Write Tests
+
+Follow existing patterns:
+
+```typescript
+// Example pattern (adapt to project style)
+describe('validateToken', () => {
+  it('should return payload for valid token', async () => {
+    // Arrange
+    const validToken = createTestToken({ userId: '123' });
+
+    // Act
+    const result = await validateToken(validToken);
+
+    // Assert
+    expect(result.userId).toBe('123');
+  });
+
+  it('should throw for expired token', async () => {
+    // Arrange
+    const expiredToken = createTestToken({ exp: Date.now() - 1000 });
+
+    // Act & Assert
+    await expect(validateToken(expiredToken)).rejects.toThrow('Token expired');
+  });
+});
+```
+
+**Economy mode:** Create essential tests only:
+- 1 happy path test
+- 1 error case test
+- Skip edge cases unless critical
+
+### 5. Verify Tests Compile
+
+```bash
+pnpm run typecheck
+```
+
+Fix any type errors in tests.
+
+### 6. Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+Write to `{output_dir}/07-tests.md`:
+- Coverage analysis
+- Test plan
+- Tests created
+- Timestamp
+- Update 00-context.md Progress table: 07-tests -> Complete
+
+### 7. Present Test Summary
+
+```
+**Test Creation Complete**
+
+**New test files:** {count}
+**Test cases added:** {count}
+
+**Coverage improvement:**
+- Before: {X}%
+- After: {Y}% (estimated)
+
+**Tests ready to run.**
+```
+
+**Proceed directly to step-08-run-tests.md**
+
+---
+
+## SUCCESS METRICS:
+
+- Existing test patterns identified
+- Coverage gaps documented
+- Tests follow project conventions
+- Tests compile without errors
+- Meaningful assertions present
+
+## FAILURE MODES:
+
+- Writing tests without reading existing patterns
+- Creating redundant test coverage
+- Tests that don't compile
+- Meaningless assertions (just checking truthy)
+- Using subagents in economy_mode
+
+---
+
+## NEXT STEP:
+
+Always proceed to `./step-08-run-tests.md` to run the tests.

package/templates/skills/apex/steps/step-08-run-tests.md

@@ -0,0 +1,207 @@
+---
+name: step-08-run-tests
+description: Test runner - execute tests until all pass
+prev_step: steps/step-07-tests.md
+next_step: COMPLETE
+---
+
+# Step 8: Run Tests
+
+## MANDATORY EXECUTION RULES:
+
+- NEVER claim tests pass when they don't
+- NEVER give up after first failure
+- ALWAYS run full test suite
+- ALWAYS fix failing tests before proceeding
+- ALWAYS re-run after each fix
+- YOU ARE A TEST RUNNER, ensuring green build
+- FORBIDDEN to proceed with failing tests
+
+## YOUR TASK:
+
+Run the test suite, fix any failures, and ensure all tests pass.
+
+---
+
+<available_state>
+From previous steps:
+
+| Variable | Description |
+|----------|-------------|
+| `{task_description}` | What was implemented |
+| `{task_id}` | Kebab-case identifier |
+| `{auto_mode}` | Auto-fix test failures |
+| `{save_mode}` | Save outputs to files |
+| `{output_dir}` | Path to output (if save_mode) |
+| Tests created | From step-07 |
+</available_state>
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Run Test Suite
+
+```bash
+pnpm run test
+```
+
+Or for specific tests:
+```bash
+pnpm run test -- --filter="auth"
+```
+
+### 2. Analyze Results
+
+**If ALL PASS:**
+Skip to step 5 (Summary).
+
+**If FAILURES:**
+For each failing test:
+
+```markdown
+## Failing Test Analysis
+
+### Test: `validateToken should throw for expired token`
+**File:** `src/auth/__tests__/handler.test.ts:25`
+**Error:** `Expected: "Token expired", Received: "Invalid token"`
+
+**Root Cause Analysis:**
+- [ ] Test bug: Incorrect assertion
+- [x] Code bug: Wrong error message
+- [ ] Setup issue: Missing mock
+
+**Fix:** Update error message in `validateToken` to be "Token expired"
+```
+
+### 3. Fix Failures
+
+**Loop until green:**
+
+```
+WHILE tests failing:
+  1. Identify root cause (test bug vs code bug)
+  2. Apply fix
+  3. Re-run tests
+  4. Log result
+```
+
+**If `{auto_mode}` = true:**
+Auto-fix obvious issues, continue loop.
+
+**If `{auto_mode}` = false AND stuck:**
+
+```yaml
+questions:
+  - header: "Test Fix"
+    question: "Test is still failing. How should we proceed?"
+    options:
+      - label: "Try alternative fix (Recommended)"
+        description: "Attempt a different approach"
+      - label: "Skip this test"
+        description: "Mark as skipped with TODO"
+      - label: "Discuss the issue"
+        description: "Need help understanding the failure"
+    multiSelect: false
+```
+
+### 4. Verify All Green
+
+Final run:
+```bash
+pnpm run test
+```
+
+**MUST show all tests passing.**
+
+### 5. Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+Write to `{output_dir}/08-run-tests.md`:
+- Test run results
+- Failures encountered and fixes
+- Final status
+- Timestamp
+- Update 00-context.md Progress table: 08-run-tests -> Complete
+
+### 6. Test Summary
+
+```
+**Test Run Complete**
+
+**Total tests:** {count}
+**Passing:** {count}
+**Failed:** 0
+
+**Iterations to green:** {count}
+
+**Fixes applied:**
+- Fixed error message in validateToken
+- Fixed mock setup in route.test.ts
+
+**All tests passing.**
+```
+
+### 7. Determine Next Step
+
+```
+IF {examine_mode} = true AND not already examined:
+    -> Load step-05-examine.md
+
+ELSE:
+    -> Workflow complete - show final summary
+```
+
+---
+
+## SUCCESS METRICS:
+
+- All tests executed
+- All failures investigated
+- Root causes identified
+- Fixes applied correctly
+- All tests passing at end
+
+## FAILURE MODES:
+
+- Claiming green when tests fail
+- Giving up after first failure
+- Skipping tests without good reason
+- Not re-running after fixes
+- Not logging fix iterations
+
+---
+
+## NEXT STEP:
+
+- **If examine_mode and not examined:** Load `./step-05-examine.md`
+- **Otherwise:** Workflow complete - show final summary
+
+## FINAL SUMMARY TEMPLATE:
+
+```
+**APEX Workflow Complete**
+
+**Task:** {task_description}
+**Task ID:** {task_id}
+
+**Implementation:**
+- Files modified: {count}
+- Files created: {count}
+
+**Quality:**
+- Typecheck: Pass
+- Lint: Pass
+- Tests: {count}/{count} passing
+
+**Review:** {examined ? "Complete" : "Skipped"}
+**Findings resolved:** {count}
+
+**Output saved:** {output_dir or "Not saved"}
+
+**Next steps:**
+- [ ] Review changes: `git diff`
+- [ ] Commit: `git commit -m "{task_description}"`
+- [ ] Push and create PR
+```

package/templates/skills/apex/templates/00-context.md

@@ -0,0 +1,46 @@
+# APEX Task: {{task_id}}
+
+**Created:** {{timestamp}}
+**Task:** {{task_description}}
+
+---
+
+## Configuration
+
+| Flag | Value |
+|------|-------|
+| Auto mode (`-a`) | {{auto_mode}} |
+| Examine mode (`-x`) | {{examine_mode}} |
+| Save mode (`-s`) | {{save_mode}} |
+| Test mode (`-t`) | {{test_mode}} |
+| Economy mode (`-e`) | {{economy_mode}} |
+
+---
+
+## User Request
+
+```
+{{original_input}}
+```
+
+---
+
+## Acceptance Criteria
+
+_To be defined in step-01-analyze_
+
+---
+
+## Progress
+
+| Step | Status |
+|------|--------|
+| 00-init | {{init_status}} |
+| 01-analyze | Pending |
+| 02-plan | Pending |
+| 03-execute | Pending |
+| 04-validate | Pending |
+| 05-examine | {{examine_status}} |
+| 06-resolve | {{examine_status}} |
+| 07-tests | {{test_status}} |
+| 08-run-tests | {{test_status}} |

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

@@ -0,0 +1,63 @@
+# Step 01: Analyze
+
+**Task:** {{task_description}}
+**Started:** {{timestamp}}
+
+---
+
+## Context Discovery
+
+### Search Keywords
+_Keywords extracted from task description_
+
+### Related Files Found
+
+| File | Lines | Contains |
+|------|-------|----------|
+| | | |
+
+### Patterns Observed
+_Patterns discovered in existing code_
+
+### Utilities Available
+_Existing utilities that can be reused_
+
+### Similar Implementations
+_Reference implementations found_
+
+### Test Patterns
+_How tests are structured in this project_
+
+---
+
+## Documentation Insights
+
+### Libraries Used
+_Libraries and their usage patterns_
+
+---
+
+## Research Findings
+
+### Common Approaches
+_Best practices discovered_
+
+---
+
+## Inferred Acceptance Criteria
+
+- [ ] AC1:
+- [ ] AC2:
+- [ ] AC3:
+
+---
+
+## Summary
+
+**Files analyzed:**
+**Patterns identified:**
+**Utilities found:**
+
+---
+
+**Status:** _Pending_