aiblueprint-cli 1.4.40 → 1.4.42

package/claude-code-config/skills/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>

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

@@ -0,0 +1,296 @@
+---
+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
+- **If context was cleared ("Execute and clear context"):** The plan file contains all APEX state variables in the "APEX Workflow Context" section. Read the plan file first and restore all variables before proceeding.
+
+## 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. Use Existing Team (created in step-02-plan)
+
+<critical>
+IMPORTANT: Claude Code Agent Teams is an EXPERIMENTAL feature.
+Ensure CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set in settings.json.
+
+The team "apex-{feature_name}" was ALREADY created in step-02-plan BEFORE the TaskList.
+Do NOT call TeamCreate again — it would reset the task list and lose all tasks.
+</critical>
+
+**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 here.
+The team MUST stay alive through validation (step-04), examine (step-05), resolve (step-06), and finish (step-09).
+Team shutdown happens ONLY in step-09-finish.md — the very last step of the APEX workflow.
+</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
+❌ **CRITICAL**: Calling TeamCreate again (team already exists from step-02-plan — re-creating resets TaskList!)
+❌ 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 — shutdown happens ONLY in step-09-finish.md
+- NEVER send shutdown_request to teammates in this step
+- Each teammate needs FULL context (plan, patterns, file references)
+- The `implementer` agent handles TaskList claiming, SendMessage reporting, and file boundaries automatically
+</critical>

package/claude-code-config/skills/{workflow-apex → apex}/steps/step-03-execute.md

@@ -32,6 +32,7 @@ next_step: steps/step-04-validate.md
 - Files to modify are known from the plan
 - Patterns to follow are documented from step-01
 - Don't add features - stick to the plan
+- **If context was cleared ("Execute and clear context"):** The plan file contains all APEX state variables in the "APEX Workflow Context" section. Read the plan file first and restore all variables before proceeding.
 
 ## YOUR TASK:
 

package/claude-code-config/skills/{workflow-apex → apex}/steps/step-04-validate.md

@@ -27,10 +27,11 @@ next_step: steps/step-05-examine.md
 
 ## CONTEXT BOUNDARIES:
 
-- Implementation from step-03 is complete
+- Implementation from step-03 (or step-03-execute-teams) is complete
 - Tests may or may not pass yet
 - Type errors may exist
 - Focus is on verification, not new implementation
+- **If `{teams_mode}` = true:** The agent team is still alive. Do NOT shutdown or dismiss teammates. Team shutdown happens in step-09-finish only.
 
 ## YOUR TASK:
 
@@ -261,4 +262,5 @@ Based on flags (check in order):
 
 <critical>
 Remember: NEVER proceed with failing checks - fix everything first!
+If teams_mode is active: NEVER shutdown teammates — they stay alive until step-09-finish!
 </critical>