nemonix-cli 1.0.0

package/src/config/claude-code-config/skills/workflow-apex/steps/step-02-plan.md

@@ -0,0 +1,422 @@
+---
+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 (READ FIRST):
+
+- 🛑 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
+- ✅ ALWAYS create a TaskList using TaskCreate tool to track all planned file changes
+- 📋 YOU ARE A PLANNER, not an implementer
+- 💬 FOCUS on "What changes need to be made where?"
+- 🚫 FORBIDDEN to use Edit, Write, or Bash tools
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 ULTRA THINK before creating the plan
+- 💾 Save plan to output file (if save_mode)
+- 📖 Reference patterns from step-01 analysis
+- 🚫 FORBIDDEN to proceed until user approves plan (unless auto_mode)
+
+## CONTEXT BOUNDARIES:
+
+- Context from step-01 (files, patterns, utilities) is available
+- Implementation has NOT started
+- User has NOT approved any changes yet
+- Plan must be complete before execution
+
+## 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. Initialize Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+```bash
+bash {skill_dir}/scripts/update-progress.sh "{task_id}" "02" "plan" "in_progress"
+```
+
+Append plan to `{output_dir}/02-plan.md` as you work.
+
+### 2. 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
+
+### 3. 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
+```
+
+### 4. 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]
+```
+
+**If `{save_mode}` = true:** Append full plan to 02-plan.md
+
+### 5. Create Task List (MANDATORY)
+
+<critical>
+You MUST create a TaskList using TaskCreate for every planned change.
+This is NOT optional - the task list tracks progress through execution.
+</critical>
+
+**Create one task per file change from the plan:**
+
+For each file in the plan, call `TaskCreate` with:
+- **subject**: `{action} {filepath}` (e.g., "Add validateToken to src/auth/handler.ts")
+- **description**: The full details of what changes are needed for this file, including specific functions, patterns to follow, and line references
+- **activeForm**: Present continuous form (e.g., "Adding validateToken to handler.ts")
+
+**Then set up dependencies using `TaskUpdate`:**
+- If file B depends on file A (e.g., B imports from A), use `addBlockedBy` to mark the dependency
+- This ensures execution follows the correct order
+
+**Example:**
+```
+TaskCreate: "Create auth types in src/types/auth.ts"
+  → description: "Create AuthToken interface, ValidateResult type. Follow pattern from src/types/user.ts"
+  → activeForm: "Creating auth types"
+
+TaskCreate: "Add validateToken to src/auth/handler.ts"
+  → description: "Add validateToken function that returns ValidateResult. Handle expired token error case."
+  → activeForm: "Adding validateToken to handler"
+  → Then: TaskUpdate with addBlockedBy: [auth-types-task-id]
+```
+
+### 6. 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
+- [ ] **TaskList created with all file changes**
+- [ ] **Task dependencies set correctly**
+
+### 7. Brainstorm Uncertainty Points
+
+<critical>
+Before proceeding, THINK about what you're NOT 100% certain about.
+DO NOT ask generic "is this plan good?" questions.
+Instead, identify SPECIFIC uncertainties and ask TARGETED questions.
+</critical>
+
+**ULTRA THINK: Identify Uncertainties**
+
+For each aspect of the plan, rate your confidence (High/Medium/Low):
+
+```markdown
+## Uncertainty Analysis
+
+| Aspect | Confidence | Uncertainty |
+|--------|------------|-------------|
+| File locations correct? | High/Medium/Low | [What's unclear] |
+| Patterns match codebase? | High/Medium/Low | [What's unclear] |
+| Dependencies complete? | High/Medium/Low | [What's unclear] |
+| Error handling approach? | High/Medium/Low | [What's unclear] |
+| User expectations for X? | High/Medium/Low | [What's unclear] |
+| Technical approach for Y? | High/Medium/Low | [What's unclear] |
+```
+
+**Identify TOP 1-4 uncertainties with Low or Medium confidence.**
+
+These are the ONLY things worth asking about.
+
+---
+
+### 8. Ask Smart Questions (if not auto_mode)
+
+**If `{auto_mode}` = true:**
+→ Skip questions, use your best judgment, proceed directly
+
+**If `{auto_mode}` = false AND you have uncertainties:**
+
+<critical>
+ONLY ask questions about things where:
+1. Multiple valid approaches exist AND the choice significantly impacts implementation
+2. User intent is genuinely ambiguous from the task description
+3. A wrong assumption could cause significant rework
+
+DO NOT ask about:
+- Implementation details you can decide yourself
+- Things you're "slightly unsure" about (just decide)
+- Generic plan approval (never ask "is this plan good?")
+</critical>
+
+**Question Types to Use:**
+
+**Type 1: Behavior Clarification**
+When user intent is genuinely unclear:
+```yaml
+questions:
+  - header: "Behavior"
+    question: "When [specific scenario], should the system [option A] or [option B]?"
+    options:
+      - label: "[Option A] (Recommended)"
+        description: "[What A does and why it might be preferred]"
+      - label: "[Option B]"
+        description: "[What B does and when it's better]"
+    multiSelect: false
+```
+
+**Type 2: Scope Clarification**
+When scope boundaries are unclear:
+```yaml
+questions:
+  - header: "Scope"
+    question: "Should we also [related thing] as part of this, or keep it focused on [core thing]?"
+    options:
+      - label: "Keep focused (Recommended)"
+        description: "Only do [core thing], faster implementation"
+      - label: "Include [related thing]"
+        description: "More complete but expands scope"
+    multiSelect: false
+```
+
+**Type 3: Technical Choice**
+When multiple valid technical approaches exist:
+```yaml
+questions:
+  - header: "Approach"
+    question: "For [specific technical decision], we can use [approach A] or [approach B]. Which fits your needs?"
+    options:
+      - label: "[Approach A] (Recommended)"
+        description: "[Tradeoffs of A - e.g., simpler but less flexible]"
+      - label: "[Approach B]"
+        description: "[Tradeoffs of B - e.g., more complex but extensible]"
+    multiSelect: false
+```
+
+**Type 4: Edge Case Handling**
+When edge case behavior is unclear:
+```yaml
+questions:
+  - header: "Edge case"
+    question: "If [edge case scenario] occurs, should we [behavior A] or [behavior B]?"
+    options:
+      - label: "[Behavior A] (Recommended)"
+        description: "[What happens with A]"
+      - label: "[Behavior B]"
+        description: "[What happens with B]"
+    multiSelect: false
+```
+
+**If you have 0 uncertainties worth asking about:**
+→ Proceed directly to execution without asking anything
+
+**Example of GOOD questions:**
+- "When a user submits invalid email format, should we show inline validation or only validate on submit?"
+- "Should the loading state show a spinner on the button or a full-page skeleton?"
+- "For rate limiting, should we limit per user or per IP address?"
+
+**Example of BAD questions (NEVER ask these):**
+- ❌ "Does this plan look good to you?"
+- ❌ "Ready to proceed with implementation?"
+- ❌ "Should I use async/await or promises?" (just decide)
+- ❌ "Is the file structure correct?" (you already verified)
+
+---
+
+### 9. Present Plan Summary
+
+```
+**Implementation Plan Ready**
+
+**Overview:** [1 sentence summary]
+
+**Files to modify:** {count} files
+**New files:** {count} files
+**Tests:** {count} test files
+
+**Key decisions made:**
+- [Decision 1 from user responses or auto-decided]
+- [Decision 2 from user responses or auto-decided]
+
+**Estimated changes:**
+- `file1.ts` - Major changes (add function, handle errors)
+- `file2.ts` - Minor changes (imports, single call)
+- `file1.test.ts` - New test file
+
+→ Proceeding to implementation...
+```
+
+### 10. Complete Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+Append to `{output_dir}/02-plan.md`:
+```markdown
+---
+## Step Complete
+**Status:** ✓ Complete
+**Files planned:** {count}
+**Tests planned:** {count}
+**Uncertainties resolved:** {count}
+**Next:** step-03-execute.md
+**Timestamp:** {ISO timestamp}
+```
+
+---
+
+## SUCCESS METRICS:
+
+✅ Complete file-by-file plan created
+✅ Logical dependency order established
+✅ All acceptance criteria mapped to changes
+✅ Test strategy defined
+✅ **TaskList created with TaskCreate for every file change**
+✅ **Task dependencies set with TaskUpdate (addBlockedBy)**
+✅ Uncertainty points identified and addressed
+✅ Smart, targeted questions asked (if not auto_mode and uncertainties exist)
+✅ NO code written or modified
+✅ Output saved (if save_mode)
+
+## 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!)
+❌ **CRITICAL**: Not creating a TaskList with TaskCreate
+❌ **CRITICAL**: Asking generic "is this plan good?" questions
+❌ **CRITICAL**: Asking about implementation details you can decide yourself
+❌ **CRITICAL**: Not brainstorming uncertainties before asking questions
+
+## PLANNING PROTOCOLS:
+
+- Structure by FILE - each file is a section
+- Include line number references from analysis
+- Every action must be specific and actionable
+- Map every AC to specific file changes
+- Plan tests alongside implementation
+
+---
+
+## NEXT STEP:
+
+After user approves via AskUserQuestion (or auto-proceed):
+
+**If `{tasks_mode}` = true OR `{teams_mode}` = true:**
+→ Load `./step-02b-tasks.md` to generate task breakdown with dependencies
+
+**If `{teams_mode}` = true (after task breakdown):**
+→ Flow continues to `./step-03-execute-teams.md` for Agent Team parallel execution
+
+**Otherwise:**
+→ Load `./step-03-execute.md` to start implementation
+
+<critical>
+Remember: Planning is ONLY about designing the approach - save all implementation for step-03!
+</critical>

package/src/config/claude-code-config/skills/workflow-apex/steps/step-02b-tasks.md

@@ -0,0 +1,301 @@
+---
+name: step-02b-tasks
+description: Generate task breakdown with dependencies from the implementation plan
+prev_step: steps/step-02-plan.md
+next_step: steps/step-03-execute.md
+---
+
+# Step 2b: Task Breakdown
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER start implementing - that's step 3
+- 🛑 NEVER write or modify code in this step
+- ✅ ALWAYS create individual task files with clear structure
+- ✅ ALWAYS include dependencies between tasks
+- ✅ ALWAYS create a README.md explaining the task graph
+- 📋 YOU ARE A TASK ARCHITECT, not an implementer
+- 💬 FOCUS on breaking down the plan into executable tasks
+- 🚫 FORBIDDEN to use Edit, Write (except for task files), or Bash tools
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Analyze the plan from step-02 before creating tasks
+- 💾 Create `tasks/` folder inside output directory (if save_mode)
+- 📖 Reference the implementation plan structure
+- 🚫 FORBIDDEN to proceed until all tasks are created
+
+## CONTEXT BOUNDARIES:
+
+- Context from step-01 (analysis) and step-02 (plan) is available
+- Implementation has NOT started
+- Tasks should map directly to plan sections
+- Each task is self-contained with all context needed
+
+## YOUR TASK:
+
+Transform the implementation plan into individual task files with clear dependencies, enabling parallel execution where possible.
+
+---
+
+<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 |
+| `{tasks_mode}` | Generate task breakdown (should be true) |
+| `{output_dir}` | Path to output (if save_mode) |
+| Plan | Full implementation plan from step-02 |
+</available_state>
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Create Tasks Directory
+
+**If `{save_mode}` = true:**
+
+```bash
+mkdir -p {output_dir}/tasks
+```
+
+### 2. Analyze Plan and Identify Tasks
+
+From the implementation plan, identify:
+
+- **Independent tasks** - Can run in parallel (no dependencies)
+- **Sequential tasks** - Must wait for other tasks to complete
+- **File-grouped tasks** - Changes to same file that could be combined
+
+**Task sizing guidelines:**
+
+- Each task should be completable in one focused session
+- Tasks should modify 1-3 files maximum
+- Complex file changes can be split into multiple tasks
+
+### 3. Create Individual Task Files
+
+For each task, create a file: `{output_dir}/tasks/task-NN-{name}.md`
+
+**Task file structure:**
+
+```markdown
+---
+id: task-NN
+name: {short-descriptive-name}
+status: pending
+priority: {high|medium|low}
+depends_on: [task-XX, task-YY]  # Empty array if no dependencies
+blocks: [task-ZZ]  # Tasks waiting for this one
+estimated_files:
+  - path/to/file1.ts
+  - path/to/file2.ts
+---
+
+# Task NN: {Descriptive Title}
+
+## Objective
+
+{One sentence describing what this task accomplishes}
+
+## Context
+
+{2-3 sentences providing background needed to complete the task}
+
+## Plan
+
+{Specific implementation steps, referencing line numbers and patterns}
+
+1. Step one
+2. Step two
+3. Step three
+
+## Files to Modify
+
+| File | Action | Changes |
+|------|--------|---------|
+| `path/to/file.ts` | Modify | Add function X, update Y |
+
+## Acceptance Criteria
+
+- [ ] AC1: {Specific testable criterion}
+- [ ] AC2: {Specific testable criterion}
+
+## Dependencies
+
+**Depends on:**
+- `task-XX`: {Why this dependency exists}
+
+**Blocks:**
+- `task-ZZ`: {Why this blocks other tasks}
+
+## Notes
+
+{Any additional context, gotchas, or considerations}
+```
+
+### 4. Build Dependency Graph
+
+Analyze task relationships:
+
+```
+task-01 ──┬──► task-02 ──► task-04
+          │
+          └──► task-03 ──► task-05
+                     ▲
+                     │
+task-06 ─────────────┘
+```
+
+Identify:
+- **Critical path** - Longest chain of dependencies
+- **Parallel groups** - Tasks that can run simultaneously
+- **Bottlenecks** - Tasks blocking many others
+
+### 5. Create README.md
+
+Create `{output_dir}/tasks/README.md`:
+
+```markdown
+# Task Breakdown: {task_description}
+
+**Generated:** {timestamp}
+**Total Tasks:** {count}
+**Parallel Groups:** {count}
+
+## Overview
+
+{1-2 sentences summarizing the task breakdown}
+
+## Dependency Graph
+
+```
+[Visual representation of task dependencies]
+```
+
+## Task Summary
+
+| ID | Name | Status | Depends On | Priority |
+|----|------|--------|------------|----------|
+| 01 | {name} | pending | - | high |
+| 02 | {name} | pending | 01 | medium |
+
+## Parallel Execution Groups
+
+**Group 1 (Start immediately):**
+- task-01: {name}
+- task-06: {name}
+
+**Group 2 (After Group 1):**
+- task-02: {name} (after task-01)
+- task-03: {name} (after task-01, task-06)
+
+**Group 3 (After Group 2):**
+- task-04: {name} (after task-02)
+- task-05: {name} (after task-03)
+
+## Critical Path
+
+task-01 → task-02 → task-04
+
+## Notes
+
+{Any additional context about the task breakdown}
+```
+
+### 6. Validate Task Breakdown
+
+Checklist:
+- [ ] All plan sections have corresponding tasks
+- [ ] No circular dependencies
+- [ ] Each task has clear acceptance criteria
+- [ ] Dependencies are logical and minimal
+- [ ] Parallel opportunities maximized
+- [ ] README accurately describes the graph
+
+### 7. Present Summary
+
+```
+**Task Breakdown Complete**
+
+**Total tasks:** {count}
+**Independent (can start now):** {count}
+**Sequential chains:** {count}
+
+**Files created:**
+- tasks/README.md
+- tasks/task-01-{name}.md
+- tasks/task-02-{name}.md
+- ...
+```
+
+**If `{auto_mode}` = true:**
+→ Skip confirmation, proceed to execution
+
+**If `{auto_mode}` = false:**
+
+```yaml
+questions:
+  - header: "Tasks"
+    question: "Task breakdown complete. Ready to proceed to implementation?"
+    options:
+      - label: "Continue to execution (Recommended)"
+        description: "Start implementing tasks in order"
+      - label: "Review tasks first"
+        description: "I want to examine the task files"
+      - label: "Adjust breakdown"
+        description: "Modify the task structure"
+    multiSelect: false
+```
+
+---
+
+## SUCCESS METRICS:
+
+✅ Tasks directory created with all task files
+✅ Each task has clear dependencies documented
+✅ README.md provides complete overview
+✅ Dependency graph has no cycles
+✅ Parallel groups identified
+✅ Critical path documented
+✅ NO code written or modified
+
+## FAILURE MODES:
+
+❌ Creating tasks without clear dependencies
+❌ Missing README.md
+❌ Circular dependencies in graph
+❌ Tasks too large or too granular
+❌ Starting to write code (that's step 3!)
+❌ **CRITICAL**: Not using AskUserQuestion for confirmation
+
+## TASK BREAKDOWN PROTOCOLS:
+
+- Each task must be self-contained with all needed context
+- Dependencies should be minimal and justified
+- Maximize parallel execution opportunities
+- Task files follow consistent structure
+- README provides birds-eye view
+
+---
+
+## NEXT STEP:
+
+After user confirms via AskUserQuestion (or auto-proceed):
+
+**If `{teams_mode}` = true:**
+→ Load `./step-03-execute-teams.md` for Agent Team parallel execution
+
+**Otherwise:**
+→ Load `./step-03-execute.md` to start implementation
+
+<critical>
+Remember: This step ONLY creates task documentation - save all implementation for step-03!
+The tasks folder gives a clear roadmap of what to implement and in what order.
+</critical>