x-implement-epic

Global Output Policy

• Language: English ONLY.
• Tone: Technical, Direct, and Concise.
• Efficiency: Remove all conversational fillers and greetings to save tokens.

Triggers

/x-implement-epic 0049                  — full run (sequential + auto-merge into epic/0049)
/x-implement-epic 0049 --parallel       — parallel story execution via worktrees
/x-implement-epic 0049 --legacy-flow    — EPIC-0042 behavior (stories → develop, no final PR)
/x-implement-epic 0049 --resume         — continue from execution-state.json
/x-implement-epic 0049 --story story-0049-0007  — single story in isolation
/x-implement-epic 0049 --dry-run        — generate execution plan only, no dispatch

Parameters

Flag	Type	Default	Description
EPIC-ID	String (4-digit)	—	Positional, required.
--parallel	Boolean	false	Opt-in parallel via worktrees. Mutually exclusive with --legacy-flow.
--legacy-flow	Boolean	false	Force EPIC-0042: stories → develop; Phase 2 and Phase 5 become no-ops. Auto-set when flowVersion=1.
--phase N	Integer	—	Execute only phase N stories. Mutually exclusive with --story.
--story ID	String	—	Execute a single story. Mutually exclusive with --phase.
--resume	Boolean	false	Continue from checkpoint. Auto-detects flowVersion.
--dry-run	Boolean	false	Generate execution plan; exit after Phase 1.
--skip-review	Boolean	false	Propagated to x-implement-story — skips specialist/TL reviews.
--auto-merge-strategy	Enum	merge	Story-PR auto-merge strategy: merge|squash|rebase.
--interactive	Boolean	false	Opt-in to 3-option menus (PROCEED/FIX-PR/ABORT) at each gate. Default: non-interactive (Rule 20 EPIC-0061).
--non-interactive	Boolean	DEPRECATED	Was opt-in; now equals default. Emits deprecation WARN. Removed in 2 releases.
--skip-pr-comments	Boolean	false	Skip Phase 4b post-gate PR-comment remediation pass.
--revert-on-failure	Boolean	false	On integrity-gate failure, revert last story merge instead of remediation agent.
--skip-smoke	Boolean	false	Bypass epic smoke gate (advisory; emergency only).

Deprecated (still parsed, warn-once): --sequential, --auto-merge, --interactive-merge, --manual-batch-approval, --single-pr, --task-tracking, --dry-run-only-comments, --auto-approve-pr (propagated as-is).

Output Contract

Field	Description
epicId	4-digit zero-padded epic identifier
epicBranch	epic/XXXX (v2) or develop (legacy)
flowVersion	"2" (default) or "1" (legacy)
phasesExecuted	List of {name, durationSec, status} per phase
storiesExecuted	List of {id, status, prNumber, prUrl} per dispatched story
finalPrUrl/Number	Final PR epic/XXXX → develop; null when legacy
integrityGatePassed	Phase 4 gate passed value
coverageLine/Branch	Filtered coverage from integrity gate envelope
reportsDir	ai/epics/epic-XXXX/reports/

Delegation Map (RULE-005 — zero inline shell invocations):

Concern	Skill	Phase
Args parsing	x-internal-normalize-args	0
DAG + execution plan	x-internal-build-epic-plan	1
epic/<ID> branch	x-internal-ensure-epic-branch	2
Per-story TDD + PR	x-implement-story	3
Integrity gate + report	x-internal-verify-epic-integrity + x-internal-write-report	4
Develop sync + final PR	x-merge-branches + x-create-pr	5
Status mutations	x-internal-update-status	all
Post-gate remediation	x-fix-epic-pr	4b (optional)

Workflow: Phase 0 (Args) → Phase 1 (Load & Plan) → Phase 2 (Branch Setup, skipped for legacy) → Phase 3 (Story Loop) → Phase 4 (Integrity Gate) → Phase 5 (Final PR, skipped for legacy).

Phase 0 — Args

<!-- TELEMETRY: phase.start --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-implement-epic Phase-0-Args

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode pre --skill x-implement-epic --phase Phase-0-Args")

Open phase tracker (close with TaskUpdate(id: phase0TaskId, status: "completed") after args normalization):

TaskCreate(subject: "EPIC-XXXX › Phase 0 - Args", activeForm: "Normalizing args and detecting flow version")

Invoke args normalizer and resolve epicId, flowVersion, flags:

Skill(skill: "x-internal-normalize-args", args: "--schema @references/args-schema.json --argv \"{raw argv}\"")

Persist interactiveMode to execution-state.json (EPIC-0068 — consumed by Stop hook enforce-continuous-flow.sh):

Skill(skill: "x-internal-update-status", args: "--file ai/epics/epic-XXXX/execution-state.json --type epic --id <EPIC-ID> --field interactiveMode --value <interactive|non-interactive>")

Value: "interactive" when --interactive passed or CLAUDE_LEGACY_INTERACTIVE=1; otherwise "non-interactive" (Rule 20 default, EPIC-0061).

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode post --skill x-implement-epic --phase Phase-0-Args")

TaskUpdate(id: phase0TaskId, status: "completed")

<!-- TELEMETRY: phase.end --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-implement-epic Phase-0-Args ok

Phase 1 — Load and Plan

<!-- TELEMETRY: phase.start --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-implement-epic Phase-1-Plan

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode pre --skill x-implement-epic --phase Phase-1-Plan")

Open phase tracker (close with TaskUpdate(id: phase1TaskId, status: "completed") after plan build):

TaskCreate(subject: "EPIC-XXXX › Phase 1 - Plan", activeForm: "Building epic execution plan")

Build DAG + execution plan:

Skill(skill: "x-internal-build-epic-plan", args: "--epic-id <ID> --mode <sequential|parallel> --output ai/epics/epic-XXXX/reports/epic-execution-plan-XXXX.md [--strict-overlap]")

Consume {phases, criticalPath, planPath}. If --dry-run=true → print plan path and stop.

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode post --skill x-implement-epic --phase Phase-1-Plan --expected-artifacts ai/epics/epic-XXXX/reports/epic-execution-plan-XXXX.md")

TaskUpdate(id: phase1TaskId, status: "completed")

<!-- TELEMETRY: phase.end --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-implement-epic Phase-1-Plan ok

<!-- phase-no-gate: Phase 2 is skipped for legacy flow; gate lives inside the conditional block -->

Phase 2 — Branch Setup (skipped for legacy)

<!-- TELEMETRY: phase.start --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-implement-epic Phase-2-Branch

Open phase tracker (close after branch ensure):

TaskCreate(subject: "EPIC-XXXX › Phase 2 - Branch", activeForm: "Ensuring epic branch exists")

Ensure epic/<ID> branch exists:

Skill(skill: "x-internal-ensure-epic-branch", args: "--epic-id <ID> --base develop --push true")

On non-zero exit → BRANCH_ENSURE_FAILED.

TaskUpdate(id: phase2TaskId, status: "completed")

<!-- TELEMETRY: phase.end --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-implement-epic Phase-2-Branch ok

Phase 3 — Story Loop

<!-- TELEMETRY: phase.start --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-implement-epic Phase-3-Execute

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode pre --skill x-implement-epic --phase Phase-3-Stories")

Open phase tracker (close with TaskUpdate(id: phase3TaskId, status: "completed") after all stories complete):

TaskCreate(subject: "EPIC-XXXX › Phase 3 - Stories", activeForm: "Executing story loop")

🔒 EXECUTION INTEGRITY (Rule 24): Each x-implement-story call below is a MANDATORY TOOL CALL.

Per-story tracking (sequential, chained via addBlockedBy):

currentStoryId = TaskCreate(subject: "EPIC-XXXX › Phase 3 › story-XXXX-YYYY", activeForm: "Implementing story-XXXX-YYYY")
[if previous story exists]: TaskUpdate(id: previousStoryId, addBlockedBy: [currentStoryId])

Skill(skill: "x-implement-story", model: "sonnet", args: "<STORY-ID> --target-branch <epicBranch> --auto-merge <strategy> [--skip-review] [--non-interactive] [--auto-approve-pr]")

TaskUpdate(id: currentStoryId, status: "completed")

Phase gate: all stories in phase N must be status=SUCCESS AND prMergeStatus=MERGED before phase N+1. Failed story → block-propagation → STORY_FAILED (unless --revert-on-failure). Resume: Phase 1 envelope resumeProjection provides reclassified story statuses.

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode post --skill x-implement-epic --phase Phase-3-Stories")

TaskUpdate(id: phase3TaskId, status: "completed")

<!-- TELEMETRY: phase.end --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-implement-epic Phase-3-Execute ok

Phase 4 — Integrity Gate

<!-- TELEMETRY: phase.start --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-implement-epic Phase-4-Gate

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode pre --skill x-implement-epic --phase Phase-4-Gate")

Open phase tracker (close with TaskUpdate(id: phase4TaskId, status: "completed") after report):

TaskCreate(subject: "EPIC-XXXX › Phase 4 - Gate", activeForm: "Running integrity gate and report")

Run integrity gate:

Skill(skill: "x-internal-verify-epic-integrity", args: "--epic-id <ID> --branch <epicBranch>")

On passed=false: remediation agent (or --revert-on-failure revert) + one retry → INTEGRITY_GATE_FAILED. Then write report:

Skill(skill: "x-internal-write-report", args: "...")

Post-gate PR-comment remediation (unless --skip-pr-comments). MANDATORY TOOL CALL — NON-NEGOTIABLE (Rule 24): Invoke the x-fix-epic-pr skill via the Skill tool whenever the gate would otherwise leave actionable Copilot comments unaddressed:

Skill(skill: "x-fix-epic-pr", model: "sonnet", args: "<EPIC-ID>")

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode post --skill x-implement-epic --phase Phase-4-Gate")

TaskUpdate(id: phase4TaskId, status: "completed")

<!-- TELEMETRY: phase.end --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-implement-epic Phase-4-Gate ok

<!-- phase-no-gate: Phase 5 is skipped for legacy flow; gate lives inside the conditional block -->

Phase 5 — Final PR (skipped for legacy)

<!-- TELEMETRY: phase.start --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-implement-epic Phase-5-Final-PR

Open phase tracker (close after PR creation):

TaskCreate(subject: "EPIC-XXXX › Phase 5 - Final PR", activeForm: "Creating final PR epic/XXXX to develop")

Sync develop into epic branch:

Skill(skill: "x-merge-branches", model: "haiku", args: "--source develop --target epic/<ID> --strategy merge")

On conflict → FINAL_PR_CONFLICTS. Then create final PR:

Skill(skill: "x-create-pr", model: "haiku", args: "--epic-id <ID> --head epic/<ID> --target-branch develop --auto-merge none --label epic-integration")

Interactive menu (only when --interactive): PROCEED / FIX-PR / ABORT. Default is non-interactive (Rule 20, EPIC-0061).

MANDATORY TOOL CALL — NON-NEGOTIABLE (Rule 24 + Rule 33): Generate epic memory summary when governance.ai-memory capability is active:

Skill(skill: "x-internal-summarize-epic", model: "haiku", args: "--epic-id <ID>")
[conditional: flag.ai_memory_enabled]

Exit code handling: 0 = proceed; 7 MANUAL_REFINEMENT_PRESENT = proceed (human override preserved); any other non-zero → log warning, proceed (memory is best-effort; does not block PR creation).

TaskUpdate(id: phase5TaskId, status: "completed")

<!-- TELEMETRY: phase.end --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-implement-epic Phase-5-Final-PR ok

Recovery

When resuming an epic that partially executed (e.g., some stories completed, CI watch failed mid-run), skip flags may be needed to bypass already-completed steps. Use CLAUDE_RECOVERY_MODE=1:

export CLAUDE_RECOVERY_MODE=1
/x-implement-epic EPIC-XXXX --resume --skip-review

CLAUDE_RECOVERY_MODE=1

When this variable is set, the PreToolUse hook enforce-no-bypass-flags.sh (EPIC-0059, Rule 45) allows --skip-review and --no-ci-watch flags on this skill without blocking. A WARNING is emitted to stderr for audit trail. The variable is propagated automatically by x-internal-resume-story when staleWarnings != [].

RULE-059-07: CLAUDE_RECOVERY_MODE=1 is the only accepted bypass variable. No other env var bypasses the enforcement hook.

Permitted bypass flags (recovery only)

Flag	Skips
--skip-review	Specialist + tech-lead reviews per story
--no-ci-watch	CI-watch polling per story PR

Error Envelope

Exit	Code	Condition
1	ARGS_INVALID	Args normalizer exit 1
2	EPIC_DIR_MISSING	ai/epics/epic-XXXX/ absent
3	STORY_FAILED	Story returned status=FAILED
4	INTEGRITY_GATE_FAILED	Phase 4 passed=false after recovery
5	FINAL_PR_CONFLICTS	Phase 5 develop-sync conflict
6	BRANCH_ENSURE_FAILED	Phase 2 non-zero exit
7	PLAN_BUILD_FAILED	Phase 1 non-zero (non-cyclic)
8	CYCLIC_DEPENDENCY	Phase 1 exit 3

Full Protocol

Per-phase detail (Phase 0 flow-version detection, Phase 3 retry/backoff/circuit-breaker, Phase 4 integrity-gate recovery algorithm + remediation-agent prompt, Phase 5 TTY-detection + gate menu), legacy-flow phase-by-phase diff (§6), resume workflow for v1/v2 (§7), SubagentResult error shape (§8), --auto-approve-pr propagation (§9), and args-schema.json reference (§1) in references/full-protocol.md. Idempotency contract and integration notes also in references.