@atlashub/smartstack-cli 1.13.2 → 1.14.1

package/templates/skills/apex/steps/step-03-execute.md

@@ -0,0 +1,178 @@
+---
+name: step-03-execute
+description: Todo-driven implementation - execute the plan file by file
+prev_step: steps/step-02-plan.md
+next_step: steps/step-04-validate.md
+---
+
+# Step 3: Execute (Implementation)
+
+## MANDATORY EXECUTION RULES:
+
+- NEVER deviate from the approved plan
+- NEVER add features not in the plan (scope creep)
+- NEVER modify files without reading them first
+- ALWAYS follow the plan file-by-file
+- ALWAYS mark todos complete immediately after each task
+- ALWAYS read files BEFORE editing them
+- YOU ARE AN IMPLEMENTER following a plan, not a designer
+- FORBIDDEN to add "improvements" not in the plan
+
+## YOUR TASK:
+
+Execute the approved implementation plan file-by-file, tracking progress with todos.
+
+---
+
+<available_state>
+From previous steps:
+
+| Variable | Description |
+|----------|-------------|
+| `{task_description}` | What to implement |
+| `{task_id}` | Kebab-case identifier |
+| `{auto_mode}` | Skip confirmations |
+| `{save_mode}` | Save outputs to files |
+| `{output_dir}` | Path to output (if save_mode) |
+| Implementation plan | File-by-file changes from step-02 |
+| Patterns | How to implement from step-01 |
+</available_state>
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Create Todos from Plan
+
+Convert each file change from the plan into todos:
+
+```
+Plan entry:
+#### `src/auth/handler.ts`
+- Add `validateToken` function
+- Handle error case: expired token
+
+Becomes:
+- [ ] src/auth/handler.ts: Add validateToken function
+- [ ] src/auth/handler.ts: Handle expired token error
+```
+
+Use TodoWrite to create the full list.
+
+### 2. Execute File by File
+
+For each todo:
+
+**2.1 Mark In Progress**
+- Only ONE todo in_progress at a time
+
+**2.2 Read Before Edit**
+```
+ALWAYS read the file before modifying:
+- Understand current structure
+- Find exact insertion points
+- Verify patterns match expectations
+```
+
+**2.3 Implement Changes**
+```
+Make changes specified in the plan:
+- Follow patterns from step-01 analysis
+- Use exact names from plan
+- Handle error cases as specified
+- NO comments unless truly necessary
+```
+
+**2.4 Mark Complete Immediately**
+- Mark todo complete RIGHT AFTER finishing
+- Don't batch completions
+
+**2.5 Log Progress (if save_mode)**
+
+Append to `{output_dir}/03-execute.md`:
+```markdown
+### file.ts
+- Added `functionName` (lines 45-78)
+- Added error handling
+```
+
+### 3. Handle Blockers
+
+**If `{auto_mode}` = true:**
+Make reasonable decision and continue.
+
+**If `{auto_mode}` = false:**
+
+```yaml
+questions:
+  - header: "Blocker"
+    question: "Encountered an issue. How should we proceed?"
+    options:
+      - label: "Use alternative approach (Recommended)"
+        description: "Description of alternative"
+      - label: "Skip this part"
+        description: "Continue without this change"
+      - label: "Stop for discussion"
+        description: "I want to discuss before continuing"
+    multiSelect: false
+```
+
+### 4. Verify Implementation
+
+After completing all todos:
+
+```bash
+pnpm run typecheck && pnpm run lint --fix
+```
+
+Fix any errors immediately.
+
+### 5. Implementation Summary
+
+```
+**Implementation Complete**
+
+**Files Modified:**
+- `src/auth/handler.ts` - Added validateToken, error handling
+- `src/api/auth/route.ts` - Integrated token validation
+
+**New Files:**
+- `src/types/auth.ts` - Auth type definitions
+
+**Todos:** {X}/{Y} complete
+```
+
+### 6. Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+Finalize `{output_dir}/03-execute.md` with:
+- Summary of all changes
+- Timestamp
+- Update 00-context.md Progress table: 03-execute -> Complete
+
+**Then proceed to validation.**
+
+---
+
+## SUCCESS METRICS:
+
+- All plan items implemented
+- All todos marked complete
+- No scope creep - only plan items
+- Files read before modification
+- Typecheck and lint pass
+
+## FAILURE MODES:
+
+- Adding features not in the plan
+- Modifying files without reading first
+- Not updating todos as you work
+- Multiple todos in_progress simultaneously
+- Ignoring type or lint errors
+
+---
+
+## NEXT STEP:
+
+After implementation complete, load `./step-04-validate.md`

package/templates/skills/apex/steps/step-04-validate.md

@@ -0,0 +1,217 @@
+---
+name: step-04-validate
+description: Self-check - run tests, verify AC, audit implementation quality
+prev_step: steps/step-03-execute.md
+next_step: steps/step-05-examine.md
+---
+
+# Step 4: Validate (Self-Check)
+
+## MANDATORY EXECUTION RULES:
+
+- NEVER claim checks pass when they don't
+- NEVER skip any validation step
+- ALWAYS run typecheck, lint, and tests
+- ALWAYS verify each acceptance criterion
+- ALWAYS fix failures before proceeding
+- YOU ARE A VALIDATOR, not an implementer
+- FORBIDDEN to proceed with failing checks
+
+## YOUR TASK:
+
+Validate the implementation by running checks, verifying acceptance criteria, and ensuring quality.
+
+---
+
+<available_state>
+From previous steps:
+
+| Variable | Description |
+|----------|-------------|
+| `{task_description}` | What was implemented |
+| `{task_id}` | Kebab-case identifier |
+| `{acceptance_criteria}` | Success criteria |
+| `{auto_mode}` | Skip confirmations |
+| `{save_mode}` | Save outputs to files |
+| `{test_mode}` | Include test steps |
+| `{examine_mode}` | Auto-proceed to review |
+| `{output_dir}` | Path to output (if save_mode) |
+| Implementation | Completed in step-03 |
+</available_state>
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Discover Available Commands
+
+Check `package.json` for exact command names:
+```bash
+cat package.json | grep -A 20 '"scripts"'
+```
+
+Look for: `typecheck`, `lint`, `test`, `build`, `format`
+
+### 2. Run Validation Suite
+
+**2.1 Typecheck**
+```bash
+pnpm run typecheck  # or npm run typecheck
+```
+
+**MUST PASS.** If fails:
+1. Read error messages
+2. Fix type issues
+3. Re-run until passing
+
+**2.2 Lint**
+```bash
+pnpm run lint
+```
+
+**MUST PASS.** If fails:
+1. Try auto-fix: `pnpm run lint --fix`
+2. Manually fix remaining
+3. Re-run until passing
+
+**2.3 Tests**
+```bash
+pnpm run test
+```
+
+**MUST PASS.** If fails:
+1. Identify failing test
+2. Determine if code bug or test bug
+3. Fix the root cause
+4. Re-run until passing
+
+### 3. Self-Audit Checklist
+
+Verify each item:
+
+**Tasks Complete:**
+- [ ] All todos from step-03 marked complete
+- [ ] No tasks skipped without reason
+- [ ] Any blocked tasks have explanation
+
+**Tests Passing:**
+- [ ] All existing tests pass
+- [ ] New tests written for new functionality
+- [ ] No skipped tests without reason
+
+**Acceptance Criteria:**
+- [ ] Each AC demonstrably met
+- [ ] Can explain how implementation satisfies AC
+- [ ] Edge cases considered
+
+**Patterns Followed:**
+- [ ] Code follows existing patterns
+- [ ] Error handling consistent
+- [ ] Naming conventions match
+
+### 4. Format Code
+
+If format command available:
+```bash
+pnpm run format
+```
+
+### 5. Final Verification
+
+Re-run all checks:
+```bash
+pnpm run typecheck && pnpm run lint
+```
+
+Both MUST pass.
+
+### 6. Present Validation Results
+
+```
+**Validation Complete**
+
+**Typecheck:** Pass
+**Lint:** Pass
+**Tests:** {X}/{X} passing
+**Format:** Applied
+
+**Acceptance Criteria:**
+- [x] AC1: Verified by [how]
+- [x] AC2: Verified by [how]
+
+**Files Modified:** {list}
+
+**Summary:** All checks passing, ready for next step.
+```
+
+### 7. Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+Write to `{output_dir}/04-validate.md`:
+- Validation results
+- AC verification
+- Timestamp
+- Update 00-context.md Progress table: 04-validate -> Complete
+
+### 8. Determine Next Step
+
+**Decision tree:**
+
+```
+IF {test_mode} = true:
+    -> Load step-07-tests.md (test analysis and creation)
+
+ELSE IF {examine_mode} = true:
+    -> Load step-05-examine.md (adversarial review)
+
+ELSE IF {auto_mode} = false:
+    -> Ask user what to do next
+
+ELSE:
+    -> Complete workflow (show final summary)
+```
+
+**If `{auto_mode}` = false:**
+
+```yaml
+questions:
+  - header: "Next"
+    question: "Validation complete. What would you like to do?"
+    options:
+      - label: "Run adversarial review"
+        description: "Deep review for security, logic, and quality"
+      - label: "Complete workflow"
+        description: "Skip review and finalize"
+      - label: "Add tests"
+        description: "Create additional tests first"
+    multiSelect: false
+```
+
+---
+
+## SUCCESS METRICS:
+
+- Typecheck passes
+- Lint passes
+- All tests pass
+- All AC verified
+- Code formatted
+- User informed of status
+
+## FAILURE MODES:
+
+- Claiming checks pass when they don't
+- Not running all validation commands
+- Skipping tests for modified code
+- Missing AC verification
+- Proceeding with failures
+
+---
+
+## NEXT STEP:
+
+Based on flags (check in order):
+- **If test_mode:** Load `./step-07-tests.md`
+- **If examine_mode OR user requests:** Load `./step-05-examine.md`
+- **Otherwise:** Workflow complete - show summary

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