@atlashub/smartstack-cli 1.13.2 → 1.14.0

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`

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