aiblueprint-cli 1.4.99 → 1.4.100

package/agents-config/skills/apex/steps/step-02b-tasks.md

@@ -1,301 +1,25 @@
 ---
 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
+description: Expand the APEX task graph into durable task packets for complex or delegated execution.
 ---
 
-# Step 2b: Task Breakdown
+# Step 2b: Expanded task packets
 
-## MANDATORY EXECUTION RULES (READ FIRST):
+Use only when the task is complex, resumable, delegated, or explicitly requests expanded task artifacts.
 
-- 🛑 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
+For each node in `{run_dir}/tasks.json`, create `{run_dir}/tasks/<id>.md` containing:
 
-## EXECUTION PROTOCOLS:
+- objective and non-goals;
+- verified context and relevant paths;
+- dependencies and dependency artifacts;
+- allowed read and write boundaries;
+- side effects and exclusive resources;
+- implementation guidance without hidden scope expansion;
+- validation commands and evidence contract;
+- stop condition and escalation path.
 
-- 🎯 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
+Keep one owner per write boundary at a time. Dependent tasks consume explicit artifacts or committed interface decisions, not assumptions about another worker's unfinished state.
 
-## CONTEXT BOUNDARIES:
+Validate that the graph has no missing IDs, circular dependencies, orphaned acceptance criteria, or overlapping mutating ownership.
 
-- 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>
+Record completion and load the exact `{execution_step}` persisted by `step-02-plan.md`. If it is missing or no longer compatible with current capabilities, return to planning and record a re-plan event instead of guessing.

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

@@ -1,296 +1,76 @@
 ---
 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
+description: Coordinate bounded APEX subagents using the capabilities available in the current harness.
+next_step: step-04-validate.md
 ---
 
-# Step 3t: Execute with Agent Teams
+# Step 3: Coordinated execution
 
-## MANDATORY EXECUTION RULES (READ FIRST):
+Use when the plan contains multiple independent units and the current harness exposes a suitable subagent lifecycle.
 
-- 🛑 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
+## Coordinator responsibilities
 
-## EXECUTION PROTOCOLS:
+The coordinator owns:
 
-- 🎯 Create team, assign tasks, monitor completion
-- 💾 Log progress to output (if save_mode)
-- 📖 Each teammate gets full task context
-- 🚫 FORBIDDEN to implement anything yourself
+- the task graph and all re-planning;
+- assignment and write-boundary exclusivity;
+- dependency and resource scheduling;
+- inspection of returned diffs and artifacts;
+- integration, conflict resolution, evidence acceptance, and completion.
 
-## CONTEXT BOUNDARIES:
+Workers own only their assigned packet. They do not approve plan changes or finish the APEX run.
 
-- 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.
+## 1. Capability preflight
 
-## YOUR TASK:
+Discover the actual spawn, message, status, wait, and shutdown operations available. Use their documented schemas. If coordinated agents are unavailable, return to `step-03-execute.md` without degrading the task contract.
 
-Coordinate a team of Claude Code agents to implement all tasks in parallel, acting purely as team lead.
+## 2. Schedule from the graph
 
----
-
-<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 as sub-agents with the `implementer` profile/type:**
-
-<critical>
-MANDATORY: Always use the `implementer` sub-agent profile/type 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, launch a sub-agent with the harness-equivalent of:
-- sub-agent profile/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 teammate sub-agent):**
-
-```
-Sub-agent:
-  profile/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}
+Choose concurrency from:
 
-    ### Files to Modify (YOUR boundary - only touch these)
-    {file list from task file}
+- dependency readiness;
+- overlapping read/write boundaries;
+- shared generated files and Git index access;
+- exclusive services, devices, ports, accounts, or fixtures;
+- expected context-transfer and integration cost;
+- current budget policy.
 
-    ### Acceptance Criteria
-    {criteria from task file}
+Task count alone is not a sizing signal. Prefer a small number of high-value workers. Run mutating assignments sequentially whenever the harness cannot guarantee safe coordination of disjoint boundaries in the shared checkout.
 
-    ### Patterns to Follow
-    {relevant patterns from step-01 analysis}
+## 3. Send bounded packets
 
-    ### 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 sub-agent launches)
-- 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`:
+Each worker receives:
 
 ```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"
+Objective:
+Non-goals:
+Dependencies and artifacts:
+Allowed paths:
+Forbidden scope:
+Relevant project rules:
+Expected output:
+Validation and evidence:
+Stop condition:
 ```
 
----
+Use a role appropriate to the unit when the harness provides one. Let local policy or the harness select the model unless the task has an evidence-backed need for a different route.
 
-## SUCCESS METRICS:
+## 4. Keep local progress moving
 
-✅ 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)
+After dispatching non-blocking sidecars, continue useful non-overlapping critical-path work. Wait only when a returned result is required for the next action. Do not duplicate delegated investigations or edits.
 
-## FAILURE MODES:
+## 5. Inspect every return
 
-❌ 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
+For each result:
 
-## 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
-
----
+1. Verify the reported files against the declared boundary.
+2. Inspect the actual diff and repository state.
+3. Re-run or validate decisive evidence.
+4. Reject noise, unrelated changes, and unsupported claims.
+5. Record completion, rework, or a re-plan event.
 
-## NEXT STEP:
+If a worker crosses scope, preserve user work, isolate the relevant diff logically, and reassign or repair only after understanding the overlap.
 
-After all tasks complete, load `./step-04-validate.md`
+## 6. Finish coordination
 
-<critical>
-Remember:
-- You are the TEAM LEAD - NEVER implement code yourself
-- ALWAYS use the `implementer` sub-agent profile/type 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>
+Close workers when their task and any follow-up are complete. The coordinator then performs one integrated diff review and proceeds to `step-04-validate.md`.