agile-epic-implement

name	agile:epic:implement
description	Orchestrates epic implementation as a team lead by parsing epic structure, building feature dependency graphs, and delegating features to existing teammates through the team inbox system (TaskCreate/TaskUpdate with addBlockedBy) and SendMessage notifications. Features execute in dependency order with parallel capability. Each completed task is cross-validated by a different teammate with a max 3-retry correction cycle. The team lead never writes code — it only coordinates. Supports session resume via state.json for crash recovery. Use this skill when the user wants to implement an epic, execute features, or delegate epic work to a team. Triggers on: "implement epic", "execute epic", "run epic", "start epic implementation", "delegate features", or any request to orchestrate multi-feature implementation with team coordination.
user-invocable	true
allowed-tools	Read, Edit, Write, Glob, Grep, Bash, Agent, SendMessage, TaskCreate, TaskList, TaskGet, TaskUpdate, TaskStop, TeamCreate, TeamDelete, AskUserQuestion

Epic Implement

Orchestrate epic implementation by parsing the epic's dependency structure and executing features in dependency order with parallel capability. The invoking agent acts as a team lead — it coordinates, delegates, and monitors but MUST NOT implement tasks directly.

Invocation

• /agile:epic:implement 136 — Target by epic number
• /agile:epic:implement agile/epics/136-feature-name — Target specific epic path

Identification Format

Level	Format	Example
Epic	NNN	136
Feature	NNN-XX	136-01
User Story	NNN-XX-U{n}	136-01-U1
Task	NNN-XX-T{nn}	136-01-T03

Team Lead Role

The agent running this skill acts exclusively as a team lead:

• Parses the epic and builds dependency graphs
• Plans feature execution order with parallel groups
• Creates tasks in the team inbox and sets dependency chains
• Delegates features to teammates via SendMessage
• Monitors progress via TaskGet
• Orchestrates cross-validation of completed work
• Updates status files and state.json
• Creates git checkpoints at phase boundaries

It does NOT: write code, compile, run tests, or execute build commands.

---

Phase 0: Initialization

Validate prerequisites and establish session state. Stop immediately with a clear message if any check fails.

Step 0: Load Required Tools

IMPORTANT: This environment may not have ToolSearch available. Use a fallback approach:

1. First, try calling TaskList with no arguments (this will fail but triggers schema loading)
2. If that fails, call Bash with echo "init" to load basic tool schemas
3. Continue with the workflow - the deferred-tool system should now have schemas loaded

If you encounter "Invalid tool parameters" errors, stop and re-run Step 0 before continuing.

Step 1: Team Check

Verify at least one teammate exists in the current session. If none found, stop: "No teammates found. Create a team before running epic implementation."

Step 2: Epic Validation

Get the epic number from the first argument. Validate that ALL of these exist in the epic folder under agile/epics/:

• design.md — Epic design document
• plan.md — Epic planning document
• epic.md — Epic specification

If any are missing, report which files are absent and stop.

Step 3: Session Detection

Check for state.json in the epic folder:

• Exists → Resume session. Read state.json and skip to the phase/feature indicated by currentPhase and currentFeatures. Do not re-create completed tasks or re-process completed features.
• Does not exist → First session. Create state.json from the template at templates/state-template.json. Initialize with epic metadata and empty feature tracking.

Early-Exit for Completed Epics (prevents unnecessary work):

Before proceeding, read epic.md and state.json. If ALL of these are true:

• epic.md status is COMPLETED
• state.json epicStatus is COMPLETED (or mismatched — see Auto-Sync below)
• All features in state.json are IMPLEMENTED or SKIPPED

Then: skip directly to Phase 5 (wrapup/analysis). Do NOT re-create tasks, do NOT spawn validation agents, do NOT re-run phases 1–4. Report: "Epic NNN is already complete. Proceeding to wrapup."

Auto-Sync on Resume:

If epic.md shows COMPLETED but state.json shows IMPLEMENTING (or mismatch):

1. Set state.json epicStatus = COMPLETED
2. Set all features to IMPLEMENTED
3. Set currentPhase to "validated"
4. Proceed to Phase 5

---

Phase 1: Understanding

Build the full execution picture from the epic's structure. Read these modules and execute:

Step 1: Epic Parser

Read modules/epic-parser.md and execute.

• Parse the feature table from epic.md (IDs, names, statuses, dependencies, parallel flags, phases)
• Parse the Feature Workflow ASCII DAG (canonical dependency source)
• Parse the Parallelization Opportunities table
• Cross-validate diagram against table (diagram wins on conflict)

Step 2: Dependency Graph

Read modules/dependency-graph.md and execute.

• Build the Feature DAG from parsed edges
• Run cycle detection (DFS). If cycle found → report exact path, stop
• Compute topological sort (execution order)
• Identify parallel groups: sets of features with no mutual dependencies that can execute concurrently

Step 3: Capture State

Update state.json with:

• executionOrder: topological sort of all features
• parallelGroups: sets of features eligible for concurrent execution
• Feature entries with their dependencies and initial status
• currentPhase: "understanding-complete"

Step 4: Update Epic Status

Update the epic status from PENDING to IMPLEMENTING in epic.md.

Step 5: Git Checkpoint

Create a git commit: chore(epic-NNN): phase 1 complete — execution plan captured in state.json

---

Phase 2: Task Order (per feature)

Prepare the next feature(s) for execution. Multiple features may be prepared simultaneously if they belong to the same parallel group.

Step 1: Identify Next Features

From state.json, find features whose dependencies are all IMPLEMENTED or SKIPPED and whose status is PENDING. If multiple independent features are ready, they form a parallel group.

Step 2: Read Feature Context

For each feature, read spec.md to understand:

• Priority and risk level
• User story points
• Acceptance criteria
• Description
• Independent test criteria

Step 3: Build Task Dependency Graph

Read modules/task-decomposer.md and execute per feature.

• Parse tasks.md and extract tasks with dependencies, parallel markers, and user story groupings
• Build the task dependency graph with predecessors and successors
• Identify cross-feature dependencies

Step 4: Extract Build Context and File Locations

Before creating tasks, invoke these modules to provide complete context:

• Build Context: Read modules/build-context.md to identify service, module path, and Maven commands
• File Finder: Read modules/file-finder.md to identify exact file paths to modify

This ensures each task assignment includes the specific build commands and file locations, reducing teammate discovery time.

Step 5: Create Tasks in Team Inbox

Read modules/task-delegator.md and execute.

• Create ALL tasks for the feature via TaskCreate before assigning any
• Each task subject: task ID prefix followed by task subject from tasks.md
• Each task description: feature context, user story, acceptance criteria, expected deliverable
• Use TaskUpdate with addBlockedBy to reference each predecessor task's inbox ID (note: inbox ID differs from the task identification number in tasks.md)

Step 5b: MANDATORY Inbox Validation (Guardrail Enforcement)

THIS STEP IS MANDATORY - NEVER SKIP

Before assigning any task to a teammate, you MUST verify tasks exist in the TaskCreate system:

1. Call TaskList to check current inbox state
2. If NO tasks found in inbox BUT state.json has taskInboxMapping:

• This indicates tasks were never properly created (resume from old state)
• You MUST recreate tasks via TaskCreate before proceeding
• Do NOT proceed to assignment without tasks in the inbox

3. If tasks exist, verify count matches tasks.md total

FAILURE TO DO THIS WILL RESULT IN:

• Tasks not tracked in the system
• No dependency coordination via addBlockedBy
• Team coordination breakdown
• No progress visibility

# Validation Check
TaskList() → if empty but state.json has mapping → RECREATE TASKS FIRST

Step 6: Update Feature Status

Update feature status from PENDING to IMPLEMENTING in spec.md and in the feature table of epic.md.

Step 7: Git Checkpoint

Create a git commit: chore(epic-NNN): feature NNN-XX tasks created in team inbox

---

Phase 3: Orchestration (per feature)

With the task dependency graph populated in the team inbox, coordinate execution and validation.

Step 0: MANDATORY Task Inbox Verification (Before ANY Assignment)

THIS CHECK IS MANDATORY - NEVER SKIP

Before assigning ANY task to ANY teammate, verify tasks exist:

1. Call TaskList()
2. If result is EMPTY:
   - STOP - Do NOT assign tasks
   - Report: "Task inbox is empty. Cannot assign. Run Phase 2 first to create tasks."
3. If tasks exist, proceed to Step 1

RULE: You cannot assign what doesn't exist in the inbox.

Step 1: Assign Tasks

Read modules/team-lead.md and execute.

• Assign tasks to team members based on their specialty (as defined in epic.md)
• Use SendMessage to notify each assigned teammate with the task details and context
• Tasks without mutual dependencies can be assigned to different teammates in parallel

CRITICAL: SendMessage Parameters When using SendMessage, ALWAYS use these exact parameters:

• type: "message"
• recipient: teammate name (e.g., "kotlin1")
• content: the message body
• summary: brief summary

NEVER use to or message — these cause "Invalid tool parameters" errors.

Step 2: Hook Awareness

The following hooks are pre-configured in .claude/settings.json and fire automatically:

• TeammateIdle — prevents teammates from going idle when unblocked tasks remain (.claude/hooks/teammate-idle-check.sh)
• TaskCompleted — verifies file changes and Java compilation before allowing completion (.claude/hooks/task-completed-verify.sh)
• PreToolUse — blocks architecture violations on Java file edits (.agile/scripts/pretooluse.py)
• PostToolUse — warns about naming/package violations; blocks team-lead task ownership (.agile/scripts/posttooluse.py)

No manual hook registration is needed. These hooks enforce guardrails automatically.

Step 3: Monitor and Validate

Read modules/status-tracker.md for status derivation rules.

For each completed task:

1. A different teammate validates the work against the task description, feature spec, and user stories
2. If corrections needed → create a correction task in the inbox, assign the appropriate teammate
3. The validate-correct cycle repeats until the task passes validation

Failure handling:

• Max validation retries: 3 attempts per task. After 3 failed validations, escalate to the user via AskUserQuestion before continuing
• State checkpoints: After each task completion or validation, update state.json with current task statuses, completed tasks, and remaining dependencies
• Resume behavior: On resume (detected in Phase 0), skip completed tasks. Re-assign only in-progress or blocked tasks

Step 4: Track Completion

• When a task is completed and validated, mark it in tasks.md: [ ] → [X]
• Continue to the next task in the dependency graph
• Repeat until all tasks in the feature are completed and validated

Step 5: Feature Complete

When all tasks are completed and validated:

• Update feature status from IMPLEMENTING to IMPLEMENTED in spec.md and epic.md
• Update state.json: move feature to completedFeatures, update currentPhase

Step 6: Git Checkpoint

Create a git commit: feat(epic-NNN): feature NNN-XX implemented and validated

---

Phase 4: Feature Iteration & Epic Validation

Feature Loop

After completing a feature in Phase 3, return to Phase 2 to identify and prepare the next feature(s). Execute Phase 2 (task preparation) and Phase 3 (orchestration) as a pair for each feature. Repeat until all features are completed.

Epic Validation

When all features reach terminal state (IMPLEMENTED or SKIPPED):

1. Validate against checklist.md — verify all checklist items and cross-cutting concerns
2. If validation passes: update epic status from IMPLEMENTING to COMPLETED in epic.md
3. If validation fails: report failures and escalate to user

Git Checkpoint

Create a git commit: feat(epic-NNN): epic completed — all features implemented and validated

---

Phase 5: Wrapup

Analysis Report

Create agile/epics/NNN-epic-name/analysis-report.md covering:

• Issues encountered during implementation
• Obstacles and how they were resolved
• Recommendations for future implementations
• Lessons learned

Error Report

Create agile/epics/NNN-epic-name/error-report.md covering:

• Tool usage mistakes
• Skill gaps identified
• Improvements needed for the agile:epic:implement skill

Team Decision

Ask the user via AskUserQuestion: "Epic NNN is complete. Would you like to shut down all team members and delete the team, or keep the current team to implement another epic?"

Act on the user's response accordingly.

---

Error Handling

Scenario	Behavior
Cycle in feature DAG	Stop. Report cycle path. User must fix epic.md
Cycle in task DAG	Skip feature. Report cycle. Other features continue
Feature missing spec.md or tasks.md	Skip with warning. Log as SKIPPED in state.json
Feature dependency not met	Skip feature, process other ready features first
Cross-feature task dep not met	Hold task. Monitor blocking task. Send CLEARED when ready
User Story gate violation	Send correction: "U{n} gate not met. Complete remaining U{n} tasks."
Validation fails 3 times	Escalate to user via AskUserQuestion
Teammate unresponsive (3 polls no progress)	Reassign to another teammate. Report if none available
Teammate crashes	Check git for committed work. Mark complete if artifacts exist
All ready features blocked	Stop. Report blocked features + unmet deps. Epic → BLOCKED
Epic stopped/paused mid-execution	Leave in_progress tasks as-is. No TaskUpdate. Go to standby
Feature Workflow diagram missing	Fall back to table Dependencies column. Emit advisory
Tasks Workflow diagram missing	Fall back to explicit deps + [P] markers. Story gates still enforced
Diagram/table dependency mismatch	Use diagram edges (canonical). Emit warning listing discrepancies
Epic already COMPLETED on resume	Auto-sync state.json, skip to Phase 5 (wrapup)

Stopping the Epic

When the user stops the epic implementation (notifies team lead to pause/stop):

For Team Lead

1. Do NOT try to complete in-progress tasks via TaskUpdate
2. Do NOT call TaskUpdate with status changes on incomplete tasks
3. Send "Epic implementation stopped" message to all teammates
4. Save current state to state.json (already done automatically after each phase)
5. Report final status to user

For Teammates

When receiving "Epic implementation stopped" message:

1. Do NOT call TaskUpdate to complete your current task
2. Do NOT attempt to finish partial work
3. Send acknowledgment to team lead
4. Go to standby mode (wait for new assignments)
5. Leave your task in in_progress state — this preserves the task for resume

Why This Matters

The TaskCompleted hook (task-completed-verify.sh) requires:

• File changes in git diff (for implementation tasks)
• Successful compilation (for Java changes)

If you try to complete a task without actual implementation:

• The hook will BLOCK the completion with exit code 2
• This causes the "TaskCompleted hook error" you're seeing

Resume Behavior

When the epic resumes:

• Phase 0 detects in-progress tasks from state.json
• Team lead reassigns those tasks to the same or different teammate
• Work continues from where it left off

Modules

Module	File	Used In
Epic Parser	modules/epic-parser.md	Phase 1
Dependency Graph	modules/dependency-graph.md	Phase 1
Task Decomposer	modules/task-decomposer.md	Phase 2
Task Delegator	modules/task-delegator.md	Phase 2
Build Context	modules/build-context.md	Phase 2
File Finder	modules/file-finder.md	Phase 2
Teammate Context	modules/teammate-context.md	Phase 2-3
Team Lead	modules/team-lead.md	Phase 3
Status Tracker	modules/status-tracker.md	Phase 3-4

Guardrails

1. Team lead never implements — delegates ALL work. Never writes code, compiles, or runs tests.
2. Existing team required — does NOT create or spawn teammates. User must create team first.
3. Inbox before assignment — ALL tasks created via TaskCreate before any are assigned to teammates.
4. Cross-validation required — a DIFFERENT teammate validates each completed task. Never self-validate.
5. 3-retry limit — after 3 failed validations, escalate to user. Never loop indefinitely.
6. State persistence — update state.json after every task completion/validation for crash recovery.
7. Git checkpoints — commit at the end of Phase 1, Phase 2, Phase 3, and Phase 4.
8. Diagram is canonical — Feature Workflow DAG is the authoritative dependency source, not the table.
9. User Story gates are hard — ALL tasks in U{n} must complete before ANY task in U{n+1} starts.
10. tasks.md is authoritative — task markers in tasks.md are ground truth for task status.
11. Checklist maintained — checklist.md cross-cutting items MUST be marked [x] as features complete. Never leave checklist stale at epic completion.
12. Early-exit for completed epics — If epic.md shows COMPLETED and all features are IMPLEMENTED, skip to Phase 5. Do not re-run implementation phases.