@atlashub/smartstack-cli 1.13.2 → 1.14.0

package/templates/skills/apex/steps/step-05-examine.md

@@ -0,0 +1,207 @@
+---
+name: step-05-examine
+description: Adversarial code review - security, logic, and quality analysis
+prev_step: steps/step-04-validate.md
+next_step: steps/step-06-resolve.md
+---
+
+# Step 5: Examine (Adversarial Review)
+
+## MANDATORY EXECUTION RULES:
+
+- NEVER skip security review
+- NEVER dismiss findings without justification
+- NEVER auto-approve without thorough review
+- ALWAYS check OWASP top 10 vulnerabilities
+- ALWAYS classify findings by severity and validity
+- ALWAYS present findings table to user
+- YOU ARE A SKEPTICAL REVIEWER, not a defender
+- FORBIDDEN to approve without thorough analysis
+
+## YOUR TASK:
+
+Conduct an adversarial code review to identify security vulnerabilities, logic flaws, and quality issues.
+
+---
+
+<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 |
+| `{economy_mode}` | No subagents, direct review |
+| `{output_dir}` | Path to output (if save_mode) |
+| Files modified | From step-03 |
+</available_state>
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Gather Changes
+
+```bash
+git diff --name-only HEAD~1
+git status --porcelain
+```
+
+Group files: source, tests, config, other.
+
+### 2. Conduct Review
+
+**If `{economy_mode}` = true:**
+
+Self-review with checklist:
+
+```markdown
+## Security Checklist
+- [ ] No SQL injection (parameterized queries)
+- [ ] No XSS (output encoding)
+- [ ] No secrets in code
+- [ ] Input validation present
+- [ ] Auth checks on protected routes
+
+## Logic Checklist
+- [ ] Error handling for all failure modes
+- [ ] Edge cases handled
+- [ ] Null/undefined checks
+- [ ] Race conditions considered
+
+## Quality Checklist
+- [ ] Follows existing patterns
+- [ ] No code duplication
+- [ ] Clear naming
+```
+
+**If `{economy_mode}` = false:**
+
+Launch parallel review agents in a SINGLE message:
+
+**Agent 1: Security** (`code-reviewer`)
+```
+Review for OWASP Top 10:
+- Injection flaws
+- Auth/authz issues
+- Data exposure
+- Security misconfiguration
+```
+
+**Agent 2: Logic** (`code-reviewer`)
+```
+Review for:
+- Edge cases not handled
+- Race conditions
+- Null handling
+- Incorrect logic
+```
+
+**Agent 3: Clean Code** (`code-reviewer`)
+```
+Review for:
+- SOLID violations
+- Code smells
+- Complexity issues
+- Duplication >20 lines
+```
+
+### 3. Classify Findings
+
+For each finding:
+
+**Severity:**
+- CRITICAL: Security vulnerability, data loss risk
+- HIGH: Significant bug, will cause issues
+- MEDIUM: Should fix, not urgent
+- LOW: Minor improvement
+
+**Validity:**
+- Real: Definitely needs fixing
+- Noise: Not actually a problem
+- Uncertain: Needs discussion
+
+### 4. Present Findings Table
+
+```markdown
+## Findings
+
+| ID | Severity | Category | Location | Issue | Validity |
+|----|----------|----------|----------|-------|----------|
+| F1 | CRITICAL | Security | auth.ts:42 | SQL injection | Real |
+| F2 | HIGH | Logic | handler.ts:78 | Missing null check | Real |
+| F3 | MEDIUM | Quality | utils.ts:15 | Complex function | Uncertain |
+
+**Summary:** {count} findings ({blocking} blocking)
+```
+
+### 5. Create Finding Todos
+
+```
+- [ ] F1 [CRITICAL] Fix SQL injection in auth.ts:42
+- [ ] F2 [HIGH] Add null check in handler.ts:78
+```
+
+### 6. Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+Write to `{output_dir}/05-examine.md`:
+- Findings table
+- Checklist results
+- Timestamp
+- Update 00-context.md Progress table: 05-examine -> Complete
+
+### 7. Get User Approval
+
+**If `{auto_mode}` = true:**
+Proceed automatically based on findings.
+
+**If `{auto_mode}` = false:**
+
+```yaml
+questions:
+  - header: "Review"
+    question: "Review complete. How would you like to proceed?"
+    options:
+      - label: "Resolve findings (Recommended)"
+        description: "Address the identified issues"
+      - label: "Skip to tests"
+        description: "Skip resolution, proceed to test creation"
+      - label: "Skip resolution"
+        description: "Accept findings, don't make changes"
+      - label: "Discuss findings"
+        description: "I want to discuss specific findings"
+    multiSelect: false
+```
+
+---
+
+## SUCCESS METRICS:
+
+- All modified files reviewed
+- Security checklist completed
+- Findings classified by severity
+- Validity assessed for each finding
+- Findings table presented
+- Todos created for tracking
+
+## FAILURE MODES:
+
+- Skipping security review
+- Not classifying by severity
+- Auto-dismissing findings
+- Launching agents sequentially
+- Using subagents when economy_mode
+
+---
+
+## NEXT STEP:
+
+After user confirms (or auto-proceed):
+
+- **If user chooses "Resolve findings":** Load `./step-06-resolve.md`
+- **If user chooses "Skip to tests" (and test_mode):** Load `./step-07-tests.md`
+- **If user chooses "Skip resolution":** Workflow complete - show summary

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.