nemonix-cli 1.0.0

package/src/config/claude-code-config/skills/workflow-apex/steps/step-03-execute-teams.md

@@ -0,0 +1,297 @@
+---
+name: step-03-execute-teams
+description: Execute implementation using Claude Code Agent Teams for parallel task execution
+prev_step: steps/step-02b-tasks.md
+next_step: steps/step-04-validate.md
+---
+
+# Step 3t: Execute with Agent Teams
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER implement code yourself - you are the TEAM LEAD
+- 🛑 NEVER use Edit, Write tools for implementation
+- ✅ ALWAYS delegate implementation to teammates
+- ✅ ALWAYS use delegate mode (Shift+Tab) to stay coordination-only
+- ✅ ALWAYS keep the team alive after tasks complete
+- 📋 YOU ARE A COORDINATOR, not an implementer
+- 💬 FOCUS on assigning tasks, monitoring progress, resolving blockers
+- 🚫 FORBIDDEN to write any implementation code
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Create team, assign tasks, monitor completion
+- 💾 Log progress to output (if save_mode)
+- 📖 Each teammate gets full task context
+- 🚫 FORBIDDEN to implement anything yourself
+
+## CONTEXT BOUNDARIES:
+
+- Task breakdown from step-02b is available
+- TaskList has all tasks with dependencies
+- You have the plan from step-02
+- Implementation has NOT started
+
+## YOUR TASK:
+
+Coordinate a team of Claude Code agents to implement all tasks in parallel, acting purely as team lead.
+
+---
+
+<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 |
+| `{teams_mode}` | Should be true |
+| `{tasks_mode}` | Should be true |
+| `{output_dir}` | Path to output (if save_mode) |
+| TaskList | All tasks with dependencies from step-02 |
+| Task files | Individual task files from step-02b (if save_mode) |
+</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}" "03" "execute-teams" "in_progress"
+```
+
+### 2. Analyze Tasks for Team Sizing
+
+Review TaskList and determine team size:
+
+| Tasks | Teammates | Rationale |
+|-------|-----------|-----------|
+| 1-2 | 1 | Sequential is fine |
+| 3-4 | 2 | Small parallel benefit |
+| 5-8 | 3-4 | Good parallelism |
+| 9+ | 4-6 | Max parallel benefit |
+
+<critical>
+NEVER create more than 6 teammates. Group related tasks if needed.
+Cap at the number of independent task groups, not total tasks.
+</critical>
+
+### 3. Map Skills to Tasks
+
+For each task, check if a matching skill should be suggested:
+
+| Task Type | Suggested Skill |
+|-----------|----------------|
+| UI/Frontend components | `/frontend-design` |
+| API endpoints | - |
+| Database/schema | - |
+| Tests | - |
+| Documentation | - |
+
+Add `skill_hint` to task assignments when relevant.
+
+### 4. Create Agent Team
+
+<critical>
+IMPORTANT: Claude Code Agent Teams is an EXPERIMENTAL feature.
+Ensure CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set in settings.json.
+</critical>
+
+**Create the team using TeamCreate:**
+
+```
+TeamCreate:
+  team_name: "apex-{feature_name}"
+  description: "APEX: {task_description}"
+```
+
+**Spawn teammates using the Task tool with `subagent_type: "implementer"`:**
+
+<critical>
+MANDATORY: Always use `subagent_type: "implementer"` for ALL teammates.
+The `implementer` agent is the dedicated APEX executor — it knows how to:
+- Claim tasks from TaskList via TaskUpdate
+- Stay within its assigned file boundaries
+- Report via SendMessage (not plain text)
+- Handle shutdown requests gracefully
+NEVER use `general-purpose` or other agent types.
+</critical>
+
+For each teammate, spawn via the Task tool:
+- `subagent_type`: `"implementer"` (MANDATORY)
+- `team_name`: `"apex-{feature_name}"`
+- `name`: `"impl-{group-name}"` (e.g., `impl-backend`, `impl-frontend`)
+- `mode`: `"bypassPermissions"`
+- `prompt`: Full task context (see template below)
+
+### 5. Spawn Teammates with Assignments
+
+**Spawn template (one Task call per teammate):**
+
+```
+Task:
+  subagent_type: "implementer"
+  team_name: "apex-{feature_name}"
+  name: "impl-{group-name}"
+  mode: "bypassPermissions"
+  prompt: |
+    You are impl-{group-name} in team apex-{feature_name}.
+
+    ## Your Assignment
+
+    **Task:** {task-id} - {task-title}
+
+    ### Objective
+    {objective from task file}
+
+    ### Plan
+    {implementation steps from task file}
+
+    ### Files to Modify (YOUR boundary — only touch these)
+    {file list from task file}
+
+    ### Acceptance Criteria
+    {criteria from task file}
+
+    ### Patterns to Follow
+    {relevant patterns from step-01 analysis}
+
+    ### Skill Hint
+    {skill to invoke, if applicable — e.g., "Use /frontend-design for UI components"}
+
+    ### Dependencies
+    {list of completed dependencies and their outputs}
+
+    IMPORTANT: Check TaskList, claim your task, implement, then report via SendMessage.
+```
+
+**Spawn rules:**
+- Spawn all INDEPENDENT teammates in PARALLEL (single message, multiple Task calls)
+- Each teammate gets ALL context (they can't see your conversation)
+- Use `mode: "bypassPermissions"` to avoid permission prompt interruptions
+- As tasks with dependencies complete, spawn teammates for dependent tasks
+- 2-4 teammates for most tasks — more adds overhead, not speed
+
+### 6. Monitor Progress
+
+**While tasks are running:**
+
+Messages from teammates arrive AUTOMATICALLY — no need to poll or check periodically.
+
+1. Wait for teammate messages (completion reports or blocker reports)
+2. If a teammate reports a blocker:
+   - Analyze the blocker
+   - Send guidance via SendMessage
+   - If blocker requires another task's output, check TaskList for its status
+3. If a teammate reports completion, verify via TaskList that the task is marked `completed`
+   (The `implementer` agent marks its own tasks complete — you don't need to do it)
+4. As tasks complete, spawn teammates for newly-unblocked dependent tasks
+
+### 7. Handle Completion
+
+**When ALL tasks are complete:**
+
+<critical>
+NEVER clean up or dismiss the team.
+Keep the team alive for potential follow-up work.
+</critical>
+
+**If `{auto_mode}` = true:**
+→ Proceed directly to step-04-validate.md
+
+**If `{auto_mode}` = false:**
+
+```yaml
+questions:
+  - header: "Team Status"
+    question: "All tasks complete. What would you like to do?"
+    options:
+      - label: "Proceed to validation (Recommended)"
+        description: "Run typecheck, lint, and verify acceptance criteria"
+      - label: "Assign additional tasks"
+        description: "Give more work to the team"
+      - label: "Message a teammate"
+        description: "Send follow-up instructions to a specific teammate"
+    multiSelect: false
+```
+
+### 8. Complete Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+Append to `{output_dir}/03-execute.md`:
+
+```markdown
+## Execution Mode: Agent Teams
+
+**Team size:** {count} teammates
+**Tasks completed:** {count}/{total}
+
+### Task Results
+| Task | Teammate | Status | Files Changed |
+|------|----------|--------|---------------|
+| task-01 | impl-backend | ✓ | file1.ts, file2.ts |
+| task-02 | impl-frontend | ✓ | file3.ts |
+
+**Team Status:** Active (kept alive for follow-up)
+
+---
+
+## Step Complete
+
+**Status:** ✓ Complete
+**Next:** step-04-validate.md
+**Timestamp:** {ISO timestamp}
+```
+
+```bash
+bash {skill_dir}/scripts/update-progress.sh "{task_id}" "03" "execute-teams" "complete"
+```
+
+---
+
+## SUCCESS METRICS:
+
+✅ All tasks assigned to teammates
+✅ All tasks completed successfully
+✅ TaskList updated with completion status
+✅ Team kept alive (NOT cleaned up)
+✅ NO implementation code written by team lead
+✅ Output saved (if save_mode)
+
+## FAILURE MODES:
+
+❌ Team lead writing implementation code
+❌ Cleaning up or dismissing the team
+❌ Using any agent type other than `implementer` for teammates
+❌ Not providing enough context to teammates
+❌ Assigning tasks with unmet dependencies
+❌ Not monitoring for blockers
+
+## BEST PRACTICES:
+
+- Give each teammate ALL context they need (they can't see your conversation)
+- Avoid assigning tasks that modify the same files to different teammates
+- Size tasks appropriately - not too large, not too small
+- Monitor actively and resolve blockers quickly
+
+---
+
+## NEXT STEP:
+
+After all tasks complete, load `./step-04-validate.md`
+
+<critical>
+Remember:
+- You are the TEAM LEAD — NEVER implement code yourself
+- ALWAYS use `subagent_type: "implementer"` when spawning teammates
+- Keep the team ALIVE after completion
+- Each teammate needs FULL context (plan, patterns, file references)
+- The `implementer` agent handles TaskList claiming, SendMessage reporting, and file boundaries automatically
+</critical>

package/src/config/claude-code-config/skills/workflow-apex/steps/step-03-execute.md

@@ -0,0 +1,239 @@
+---
+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 (READ FIRST):
+
+- 🛑 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
+- 💬 FOCUS on executing the plan exactly as approved
+- 🚫 FORBIDDEN to add "improvements" not in the plan
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Create todos from plan before starting
+- 💾 Mark todos complete immediately after each task
+- 📖 Read each file BEFORE modifying it
+- 🚫 FORBIDDEN to have multiple todos in_progress simultaneously
+
+## CONTEXT BOUNDARIES:
+
+- Plan from step-02 is approved and must be followed
+- Files to modify are known from the plan
+- Patterns to follow are documented from step-01
+- Don't add features - stick to 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. Initialize Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+```bash
+bash {skill_dir}/scripts/update-progress.sh "{task_id}" "03" "execute" "in_progress"
+```
+
+Append logs to `{output_dir}/03-execute.md` as you work.
+
+### 2. 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.
+
+### 3. Execute File by File
+
+For each todo:
+
+**3.1 Mark In Progress**
+- Only ONE todo in_progress at a time
+
+**3.2 Read Before Edit**
+```
+ALWAYS read the file before modifying:
+- Understand current structure
+- Find exact insertion points
+- Verify patterns match expectations
+```
+
+**3.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
+```
+
+**3.4 Mark Complete Immediately**
+- Mark todo complete RIGHT AFTER finishing
+- Don't batch completions
+
+**3.5 Log Progress (if save_mode)**
+```markdown
+### ✓ src/auth/handler.ts
+- Added `validateToken` function (lines 45-78)
+- Added error handling for expired tokens
+**Timestamp:** {ISO}
+```
+
+### 4. 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
+```
+
+### 5. Verify Implementation
+
+After completing all todos:
+
+```bash
+pnpm run typecheck && pnpm run lint --fix
+```
+
+Fix any errors immediately.
+
+### 6. 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
+```
+
+**If `{auto_mode}` = true:**
+→ Proceed to validation
+
+**If `{auto_mode}` = false:**
+
+```yaml
+questions:
+  - header: "Execute"
+    question: "Implementation complete. Ready to validate?"
+    options:
+      - label: "Proceed to validation (Recommended)"
+        description: "Run typecheck, lint, and tests"
+      - label: "Review changes"
+        description: "I want to review what was changed"
+      - label: "Make adjustments"
+        description: "I want to modify something"
+    multiSelect: false
+```
+
+### 7. Complete Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+Append to `{output_dir}/03-execute.md`:
+```markdown
+---
+## Step Complete
+**Status:** ✓ Complete
+**Files modified:** {count}
+**Todos completed:** {count}
+**Next:** step-04-validate.md
+**Timestamp:** {ISO timestamp}
+```
+
+---
+
+## SUCCESS METRICS:
+
+✅ All plan items implemented
+✅ All todos marked complete
+✅ No scope creep - only plan items
+✅ Files read before modification
+✅ Typecheck and lint pass
+✅ Progress logged (if save_mode)
+
+## 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
+❌ **CRITICAL**: Not using AskUserQuestion for blockers
+
+## EXECUTION PROTOCOLS:
+
+- Follow the plan EXACTLY
+- Read before write
+- One file at a time
+- Update todos in real-time
+- Fix errors immediately
+
+---
+
+## NEXT STEP:
+
+After implementation complete, load `./step-04-validate.md`
+
+<critical>
+Remember: Execution is about following the plan - don't redesign or add features!
+</critical>