@danmoisan/drm-copilot-mcp 1.0.13 → 1.0.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danmoisan/drm-copilot-mcp",
-  "version": "1.0.13",
+  "version": "1.0.14",
   "description": "Stdio MCP server exposing drm-copilot repo-automation tools.",
   "license": "MIT",
   "type": "commonjs",

package/resources/claude-customizations/.claude/agents/epic-orchestrator.md

@@ -65,6 +65,30 @@ On every invocation:
 5. If no checkpoint exists or the objective is new, begin from manifest parsing
    (`docs/features/epics/<epic-slug>/epic.md`).
 
+## Invocation Origin
+
+You are invoked from the main session — via `/epic-orchestrate <epic-manifest-path>`, via
+`/epic-run <epic-slug>` (which replays the kickoff artifact `epic-planner` emitted), or by a
+direct prompt. You delegate to `Agent(orchestrator)`, so an invocation that itself
+originates from an `orchestrator` agent would nest `orchestrator` inside its own delegation
+chain; the PreToolUse hook `.claude/hooks/enforce-epic-invocation-origin.ps1` denies any
+`Agent(epic-orchestrator)` or `Agent(epic-planner)` call whose calling agent is `orchestrator`
+(`EPIC_INVOCATION_ORIGIN_BLOCKED`).
+
+## Prepared-Epic Execution (epic-planner Handoff)
+
+When the epic was prepared by `epic-planner` (the integration branch already exists and
+`docs/features/epics/<epic-slug>/epic-kickoff.md` is present), each child feature folder already
+contains its issue, research, `spec.md`, `user-story.md`, an approved atomic plan, and a
+recorded preflight clearance. In that case:
+
+1. Do not recreate the integration branch; fetch and reuse it.
+2. Each child `Agent(orchestrator)` delegation prompt cites the child's committed `plan-path`
+   and instructs the run to resume at atomic execution from that plan rather than re-running
+   promotion, research, or planning.
+3. The wave barrier, merge-on-green fan-in, and final integration-to-`main` PR proceed
+   unchanged per the `epic-orchestrate` skill.
+
 ## Delegation Model
 
 You delegate exclusively through two channels:

package/resources/claude-customizations/.claude/agents/epic-planner.md

@@ -0,0 +1,121 @@
+---
+name: epic-planner
+model: opus
+description: Epic-scale planning agent that fully scopes an epic before any execution. It decomposes the objective into child features, computes the dependency graph and wave layering, assesses per-feature complexity, drives per-feature preparation (promotion, research, spec/user-story, atomic plan, preflight clearance) through parallel preparation-mode Agent(orchestrator) delegations, commits all planning outputs to the epic integration branch, and emits the epic-orchestrator kickoff prompt artifact. Performs no atomic execution. Must not be invoked from an orchestrator agent (enforced by enforce-epic-invocation-origin.ps1).
+tools:
+  - "Agent(orchestrator)"
+  - Read
+  - Grep
+  - Glob
+  - "Write(docs/features/epics/**)"
+  - "Edit(docs/features/epics/**)"
+  - "Write(artifacts/orchestration/**)"
+  - "Edit(artifacts/orchestration/**)"
+  - "Bash(git *)"
+  - "Bash(gh *)"
+  - "mcp__drm-copilot__validate_orchestration_artifacts"
+skills:
+  - policy-compliance-order
+  - epic-plan
+  - epic-orchestrate
+  - feature-promotion-lifecycle
+  - atomic-plan-contract
+  - evidence-and-timestamp-conventions
+memory: project
+---
+
+# Epic Planner Agent
+
+You are the epic-scale planning agent. You take an epic-sized objective from raw intent to a
+fully prepared, execution-ready state without performing any execution. You are distinct from
+`.claude/agents/epic-orchestrator.md`: `epic-orchestrator` schedules and executes an already
+planned epic; you produce that plan. Your terminal deliverable is a committed epic integration
+branch containing the epic manifest, one prepared feature folder per child feature (issue,
+research, spec, user-story, approved atomic plan, preflight clearance), and a kickoff prompt
+artifact the user replays to launch `epic-orchestrator` on command.
+
+## Skill
+
+Apply the `epic-plan` skill (`.claude/skills/epic-plan/SKILL.md`) as the canonical procedure for
+the epic-worthiness gate, decomposition, wave computation, complexity assessment, the
+integration-branch lifecycle, preparation-mode child delegation, fan-in of prepared work, the
+kickoff-prompt artifact, and checkpoint persistence. This agent frames the *who* and *when*; the
+skill documents the *how* in full. The epic manifest schema and wave-assignment formula are
+defined once in the `epic-orchestrate` skill and are consumed here, not redefined.
+
+## Invocation Origin
+
+You are invoked from the main session only. You delegate to `Agent(orchestrator)`, so an
+invocation that itself originates from an `orchestrator` agent would nest `orchestrator` inside
+its own delegation chain; the PreToolUse hook
+`.claude/hooks/enforce-epic-invocation-origin.ps1` denies any `Agent(epic-planner)` or
+`Agent(epic-orchestrator)` call whose calling agent is `orchestrator`
+(`EPIC_INVOCATION_ORIGIN_BLOCKED`).
+
+## Startup Protocol
+
+On every invocation:
+
+1. Read `CLAUDE.md` for repository tone policy and architecture context.
+2. Read applicable `.claude/rules/` files for languages in scope.
+3. Read `artifacts/orchestration/epic-planner-state.json` to check for existing planning
+   checkpoint state.
+4. If a valid checkpoint exists with a matching objective, resume from the recorded `next_step`,
+   re-deriving durable ground truth from the integration branch, the epic manifest, and the
+   prepared feature folders rather than from in-memory notifications alone.
+5. If no checkpoint exists or the objective is new, begin from the epic-worthiness gate.
+
+## Epic-Worthiness Gate
+
+Your first planning action is to assess whether the objective warrants an epic at all, per the
+`epic-plan` skill's criteria (independent child-feature count and per-feature change budget).
+When the objective does not warrant an epic, report that finding to the user with the rationale
+and offer to delegate the work directly to a single `Agent(orchestrator)` run as one feature.
+Do not build epic scaffolding for a single-feature objective; proceed to epic planning only when
+the gate passes or the user directs you to.
+
+## Delegation Model
+
+You delegate exclusively through `Agent(orchestrator)`, one delegation per child feature, each
+carrying the preparation-mode kickoff line defined in the `epic-plan` skill. Each child
+`orchestrator` runs promotion, research, feature documents, atomic planning, and preflight
+clearance under `route_id: preparation`, then stops before any execution. You do not delegate
+directly to `atomic-planner`, `atomic-executor`, `task-researcher`, or `prd-feature`; those
+delegations belong to each child's own `orchestrator` instance. You never delegate to
+`Agent(epic-orchestrator)`; executing the plan is the user's explicit next command.
+
+## Integration Branch
+
+All planning outputs are committed to the epic integration branch
+(`epic/<epic-slug>-integration`, created off `origin/main` if absent), so `epic-orchestrator`
+can later execute against the exact planned state. The branch lifecycle and fan-in procedure are
+defined in the `epic-plan` skill.
+
+## Kickoff Prompt Artifact
+
+At completion you write the epic-orchestrator kickoff prompt to
+`artifacts/orchestration/epic-kickoff-<epic-slug>.md` and commit a durable copy at
+`docs/features/epics/<epic-slug>/epic-kickoff.md` (the `artifacts/` tree is gitignored). The
+artifact contains the exact prompt the user replays to launch `Agent(epic-orchestrator)` against
+the prepared epic, per the template in the `epic-plan` skill.
+
+## Checkpoint Persistence
+
+Update `artifacts/orchestration/epic-planner-state.json` after every completed step with:
+`objective`, `epic_feature_folder`, `epic_manifest_path`, `integration_branch`,
+`epic_worthiness` (`{verdict, rationale}`), `features[]` (per-feature `issue_num`,
+`feature_folder`, `depends_on`, `wave`, `complexity_band`, `preparation_status`, `plan_path`,
+`preflight_status`), `kickoff_prompt_path`, `completed_steps`, `next_step`, and `last_updated`.
+
+## Completion Requirements
+
+Do not report completion until:
+
+1. The epic manifest at `docs/features/epics/<epic-slug>/epic.md` parses against the
+   `epic-orchestrate` schema with a cycle-free dependency graph.
+2. Every child feature has an issue, an active feature folder, research, `spec.md`,
+   `user-story.md`, an approved atomic plan, and a recorded `PREFLIGHT: ALL CLEAR`.
+3. All planning outputs are committed and pushed on the integration branch.
+4. The kickoff prompt artifact exists at both paths listed above.
+5. The final report lists each feature's `plan-path:` and preflight status, plus the kickoff
+   artifact path.

package/resources/claude-customizations/.claude/agents/orchestrator.md

@@ -4,7 +4,6 @@ model: opus
 description: Deterministic repository orchestrator that estimates change budget, selects small or large workflow path, delegates to specialist subagents, persists checkpoint state, and enforces completion gates proactively.
 tools:
   - "Agent(atomic-planner,atomic-executor,feature-review,task-researcher,prd-feature,staged-review,epic-review,status-updater,pr-author,commit-message,human-exception-runbook,python-typed-engineer,powershell-typed-engineer,csharp-typed-engineer,typescript-engineer)"
-  - "Agent(epic-orchestrator)"
   - Read
   - Grep
   - Glob
@@ -75,7 +74,8 @@ The first action is always to estimate the change budget by identifying likely a
 
 - **Small path** (1–3 production files + corresponding tests): promotion, active folder, minimal plan, implementation, QC, small-audit review.
 - **Large path** (4+ production files or cross-cutting changes): scope, promotion, research, spec, atomic planning, atomic execution, feature review.
-- **Epic path**: the objective names or references an epic manifest (`docs/features/epics/<epic-slug>/epic-plan.md`) or explicitly requests multi-feature/epic orchestration. On this outcome the orchestrator delegates to `Agent(epic-orchestrator)` with the manifest path, instead of running change-budget/small/large routing itself.
+- **Epic outcome**: the objective names or references an epic manifest (`docs/features/epics/<epic-slug>/epic.md`) or explicitly requests multi-feature/epic orchestration. On this outcome the orchestrator does not route the work itself and does not delegate it: it halts and reports that epic-scale objectives are invoked from the main session — `Agent(epic-planner)` for planning, `Agent(epic-orchestrator)` for execution. The orchestrator never invokes either epic agent; both delegate to `Agent(orchestrator)`, so an orchestrator-originated invocation would nest orchestrator inside its own delegation chain, and the PreToolUse hook `enforce-epic-invocation-origin.ps1` denies it (`EPIC_INVOCATION_ORIGIN_BLOCKED`).
+- **Preparation mode (epic planning)**: the delegation prompt carries the literal marker `Preparation mode: true` (issued by `epic-planner` per the `epic-plan` skill). The orchestrator selects `route_id: preparation` and runs promotion, research, feature documents, atomic planning, and the atomic-executor preflight only, per `## Preparation Mode` in `.claude/skills/orchestrate/SKILL.md`. It stops after `PREFLIGHT: ALL CLEAR` with `next_step: "S5_atomic_execution"`, out-of-scope step statuses `not-applicable`, and no completion assertion; atomic execution, PR authoring, and CI monitoring are out of scope for the run.
 
 ## Delegation Model
 

package/resources/claude-customizations/.claude/hooks/enforce-epic-invocation-origin.ps1

@@ -0,0 +1,246 @@
+<#
+.SYNOPSIS
+    Pre-tool-use hook that blocks epic-planner and epic-orchestrator delegations
+    originating from an orchestrator agent.
+
+.DESCRIPTION
+    Invoked by the Claude Code PreToolUse hook on the "Agent" matcher before any
+    Agent (Task) call runs. Activates only when the delegation target
+    subagent_type is 'epic-planner' or 'epic-orchestrator'.
+
+    Caller identity resolution:
+      - The full PreToolUse payload (CLAUDE_HOOK_INPUT) carries a top-level
+        'agent_type' field only when the tool call is made from inside a
+        subagent context. A main-thread call carries no 'agent_type'.
+      - The Agent tool input (CLAUDE_TOOL_INPUT, or the payload's 'tool_input'
+        object) carries the delegation target 'subagent_type'.
+
+    Decision procedure:
+      1. Resolve the target subagent_type from CLAUDE_TOOL_INPUT, falling back
+         to the payload's tool_input object. A non-epic target allows.
+      2. Resolve the calling agent_type from the payload. An absent or empty
+         agent_type indicates a main-thread invocation, which allows.
+      3. Deny with reason EPIC_INVOCATION_ORIGIN_BLOCKED when the calling
+         agent_type is exactly 'orchestrator'. Both epic agents delegate to
+         Agent(orchestrator); an orchestrator-originated invocation would nest
+         orchestrator inside its own delegation chain.
+
+.NOTES
+    Compatible with PowerShell 7+. No external module dependencies. Read-only
+    validation gate; malformed JSON in either payload throws so the entrypoint
+    exits 1.
+#>
+[CmdletBinding()]
+param()
+
+$script:GatedSubagentTypes = @('epic-planner', 'epic-orchestrator')
+$script:ProhibitedCallerAgentType = 'orchestrator'
+
+function Get-EpicInvocationOriginAllowDecision {
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param()
+
+    return [ordered]@{
+        hookSpecificOutput = [ordered]@{
+            hookEventName      = 'PreToolUse'
+            permissionDecision = 'allow'
+        }
+    }
+}
+
+function Get-EpicInvocationOriginBlockDecision {
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Reason
+    )
+
+    return [ordered]@{
+        hookSpecificOutput = [ordered]@{
+            hookEventName            = 'PreToolUse'
+            permissionDecision       = 'deny'
+            permissionDecisionReason = $Reason
+        }
+    }
+}
+
+function ConvertFrom-EpicInvocationOriginPayload {
+    <#
+    .SYNOPSIS
+        Parses a raw JSON payload string, returning $null for a blank payload
+        and throwing a named error for malformed JSON.
+    .PARAMETER RawPayload
+        The raw JSON text under evaluation.
+    .PARAMETER PayloadName
+        The payload's environment-variable name, used in the error message.
+    .OUTPUTS
+        System.Object or $null
+    #>
+    [CmdletBinding()]
+    param(
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $RawPayload,
+
+        [Parameter(Mandatory)]
+        [string] $PayloadName
+    )
+
+    if ([string]::IsNullOrWhiteSpace($RawPayload)) {
+        return $null
+    }
+
+    try {
+        return $RawPayload | ConvertFrom-Json -ErrorAction Stop
+    } catch {
+        throw "enforce-epic-invocation-origin hook received malformed JSON in ${PayloadName}: $_"
+    }
+}
+
+function Get-EpicInvocationOriginTargetSubagent {
+    <#
+    .SYNOPSIS
+        Resolves the delegation target subagent_type from the tool input,
+        falling back to the full payload's tool_input object.
+    .PARAMETER ToolInput
+        Parsed CLAUDE_TOOL_INPUT object, or $null when absent.
+    .PARAMETER HookInput
+        Parsed CLAUDE_HOOK_INPUT object, or $null when absent.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [AllowNull()]
+        $ToolInput,
+
+        [AllowNull()]
+        $HookInput
+    )
+
+    if ($null -ne $ToolInput -and
+        (@($ToolInput.PSObject.Properties.Name) -contains 'subagent_type') -and
+        -not [string]::IsNullOrWhiteSpace([string]$ToolInput.subagent_type)) {
+        return [string]$ToolInput.subagent_type
+    }
+
+    if ($null -ne $HookInput -and
+        (@($HookInput.PSObject.Properties.Name) -contains 'tool_input')) {
+        $nested = $HookInput.tool_input
+        if ($null -ne $nested -and
+            (@($nested.PSObject.Properties.Name) -contains 'subagent_type') -and
+            -not [string]::IsNullOrWhiteSpace([string]$nested.subagent_type)) {
+            return [string]$nested.subagent_type
+        }
+    }
+
+    return $null
+}
+
+function Get-EpicInvocationOriginCallerAgentType {
+    <#
+    .SYNOPSIS
+        Resolves the calling agent_type from the full hook payload. Returns
+        $null for a main-thread invocation (no agent_type field).
+    .PARAMETER HookInput
+        Parsed CLAUDE_HOOK_INPUT object, or $null when absent.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [AllowNull()]
+        $HookInput
+    )
+
+    if ($null -eq $HookInput) {
+        return $null
+    }
+    if (@($HookInput.PSObject.Properties.Name) -notcontains 'agent_type') {
+        return $null
+    }
+
+    $agentType = [string]$HookInput.agent_type
+    if ([string]::IsNullOrWhiteSpace($agentType)) {
+        return $null
+    }
+    return $agentType
+}
+
+function Invoke-EpicInvocationOriginDecision {
+    <#
+    .SYNOPSIS
+        Parses the hook payloads and returns an allow-or-block decision.
+    .PARAMETER HookInputRaw
+        The raw full PreToolUse payload JSON supplied via CLAUDE_HOOK_INPUT.
+    .PARAMETER ToolInputRaw
+        The raw Agent tool input JSON supplied via CLAUDE_TOOL_INPUT.
+    .OUTPUTS
+        System.Collections.Specialized.OrderedDictionary
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $HookInputRaw,
+
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $ToolInputRaw
+    )
+
+    # The tool input identifies the delegation target; a non-epic target is
+    # outside this hook's scope, so the hook input is not parsed for it.
+    $toolInput = ConvertFrom-EpicInvocationOriginPayload -RawPayload $ToolInputRaw -PayloadName 'CLAUDE_TOOL_INPUT'
+    $hookInputParsed = $false
+    $hookInput = $null
+
+    $target = Get-EpicInvocationOriginTargetSubagent -ToolInput $toolInput -HookInput $hookInput
+    if (-not $target -and -not [string]::IsNullOrWhiteSpace($HookInputRaw)) {
+        # Fallback: some harness surfaces supply only the full payload, whose
+        # tool_input object carries the target subagent_type.
+        $hookInput = ConvertFrom-EpicInvocationOriginPayload -RawPayload $HookInputRaw -PayloadName 'CLAUDE_HOOK_INPUT'
+        $hookInputParsed = $true
+        $target = Get-EpicInvocationOriginTargetSubagent -ToolInput $toolInput -HookInput $hookInput
+    }
+
+    if (-not $target -or $script:GatedSubagentTypes -notcontains $target) {
+        return Get-EpicInvocationOriginAllowDecision
+    }
+
+    if (-not $hookInputParsed) {
+        $hookInput = ConvertFrom-EpicInvocationOriginPayload -RawPayload $HookInputRaw -PayloadName 'CLAUDE_HOOK_INPUT'
+    }
+
+    # An absent agent_type marks a main-thread invocation, which is the
+    # intended entry point for both epic agents; only an orchestrator-context
+    # invocation is prohibited.
+    $caller = Get-EpicInvocationOriginCallerAgentType -HookInput $hookInput
+    if ($caller -ne $script:ProhibitedCallerAgentType) {
+        return Get-EpicInvocationOriginAllowDecision
+    }
+
+    $reason = "EPIC_INVOCATION_ORIGIN_BLOCKED: Agent($target) must not be invoked from an orchestrator agent. Both epic-planner and epic-orchestrator delegate to Agent(orchestrator), so an orchestrator-originated invocation would nest orchestrator inside its own delegation chain. Invoke $target from the main session instead."
+    return Get-EpicInvocationOriginBlockDecision -Reason $reason
+}
+
+# Guard allows dot-sourcing in tests without executing the entrypoint.
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+try {
+    $decision = Invoke-EpicInvocationOriginDecision -HookInputRaw $env:CLAUDE_HOOK_INPUT -ToolInputRaw $env:CLAUDE_TOOL_INPUT
+} catch {
+    Write-Error $_
+    exit 1
+}
+
+$decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
+
+exit 0

package/resources/claude-customizations/.claude/settings.json

@@ -1,6 +1,5 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-settings.json",
-  "agent": "orchestrator",
   "permissions": {
     "allow": [
       "Bash(git *)",
@@ -39,7 +38,11 @@
       "Agent(csharp-typed-engineer)",
       "Agent(typescript-engineer)",
       "Agent(epic-orchestrator)",
+      "Agent(epic-planner)",
       "Skill(orchestrate *)",
+      "Skill(epic-plan *)",
+      "Skill(epic-orchestrate *)",
+      "Skill(epic-run *)",
       "Skill(commit-message *)",
       "Skill(pr-author *)",
       "Skill(research-issue *)",
@@ -173,13 +176,17 @@
           {
             "type": "command",
             "command": "pwsh -NoProfile -File .claude/hooks/enforce-model-routing-receipt.ps1"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File .claude/hooks/enforce-epic-invocation-origin.ps1"
           }
         ]
       }
     ],
     "SubagentStop": [
       {
-        "matcher": "atomic-planner|atomic-executor|feature-review|task-researcher|prd-feature|staged-review|epic-review|status-updater|python-typed-engineer|powershell-typed-engineer|csharp-typed-engineer|typescript-engineer|orchestrator|epic-orchestrator",
+        "matcher": "atomic-planner|atomic-executor|feature-review|task-researcher|prd-feature|staged-review|epic-review|status-updater|python-typed-engineer|powershell-typed-engineer|csharp-typed-engineer|typescript-engineer|orchestrator|epic-orchestrator|epic-planner",
         "hooks": [
           {
             "type": "command",

package/resources/claude-customizations/.claude/skills/epic-orchestrate/SKILL.md

@@ -2,10 +2,17 @@
 name: epic-orchestrate
 description: Route a multi-feature epic through the deterministic wave-scheduling, integration-branch, and fan-in workflow for the epic-orchestrator agent.
 argument-hint: "[epic-manifest-path]"
+context: fork
+agent: epic-orchestrator
 ---
 
 # Epic Orchestrate Skill
 
+A user invocation (`/epic-orchestrate <epic-manifest-path>`) forks the `epic-orchestrator`
+agent with this procedure in context. The epic manifest path (or epic slug) for this run is:
+
+$ARGUMENTS
+
 This skill frames work for the `epic-orchestrator` agent, parallel to how
 `.claude/skills/orchestrate/SKILL.md` frames work for `orchestrator`. It documents the epic
 checkpoint handling, wave computation, integration-branch lifecycle, wave barrier,

package/resources/claude-customizations/.claude/skills/epic-plan/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: epic-plan
+description: Scope and prepare a multi-feature epic end-to-end before execution for the epic-planner agent - epic-worthiness gate, decomposition, dependency-wave design, complexity assessment, preparation-mode child orchestrator delegations, integration-branch fan-in, and the epic-orchestrator kickoff prompt artifact.
+argument-hint: "[epic objective or epic-manifest-path]"
+context: fork
+agent: epic-planner
+---
+
+# Epic Plan Skill
+
+A user invocation (`/epic-plan <objective>`) forks the `epic-planner` agent with this procedure
+in context. The epic objective (or an existing epic-manifest path) for this run is:
+
+$ARGUMENTS
+
+This skill frames work for the `epic-planner` agent, parallel to how
+`.claude/skills/epic-orchestrate/SKILL.md` frames work for `epic-orchestrator`. It documents the
+epic-worthiness gate, decomposition and wave design, per-feature complexity assessment, the
+preparation-mode child delegation contract, integration-branch fan-in, the kickoff-prompt
+artifact, and planning-checkpoint handling so the procedure is not re-derived ad hoc on each
+planning run. Planning ends at preflight clearance; no atomic execution, PR authoring, or CI
+monitoring occurs under this skill.
+
+## Prerequisites
+
+Before proceeding, `epic-planner` must:
+
+1. Read `CLAUDE.md` for repository tone policy and architectural context.
+2. Read applicable `.claude/rules/` files for the languages in scope.
+3. Read the policy files listed in the compliance reading order section of `CLAUDE.md`.
+
+## Epic-Worthiness Gate
+
+The first planning step is a deterministic assessment of whether the objective warrants an epic:
+
+- Decompose the objective into candidate child features, each independently mergeable with its
+  own issue, feature folder, and PR.
+- The objective warrants an epic only when BOTH hold:
+  1. The decomposition yields two or more child features, and
+  2. At least one candidate feature exceeds — or the combined scope clearly exceeds — a single
+     large-path feature's practical change budget.
+
+When the gate fails, `epic-planner` reports to the user that the complexity does not warrant an
+epic, states the rationale (feature count and estimated change budget), and offers to delegate
+the work directly to a single `Agent(orchestrator)` run as one feature. It records the verdict
+under `epic_worthiness` in the planning checkpoint and proceeds with epic scaffolding only when
+the gate passes or the user explicitly directs it to.
+
+## Decomposition and Wave Design
+
+For an epic-worthy objective:
+
+1. Define the epic slug and epic home `docs/features/epics/<epic-slug>/`.
+2. Author `docs/features/epics/<epic-slug>/epic.md` using the manifest frontmatter schema
+   defined in the `epic-orchestrate` skill (that skill is the single schema authority; do not
+   redefine it here). The Markdown body carries the epic narrative: goal, scope, non-goals,
+   shared design, and decomposition rationale.
+3. Derive `depends_on` edges from real upstream/downstream contracts only; do not add ordering
+   edges for stylistic reasons, because every edge reduces execution parallelism.
+4. Compute wave assignment with the longest-path layering formula from the `epic-orchestrate`
+   skill (`scripts/dev_tools/epic_wave_computation.py` is the tested reference implementation)
+   and reject cycles or unresolved references before any preparation is delegated.
+5. Record the planned waves in the planning checkpoint and in the epic narrative.
+
+At manifest-authoring time child issues do not exist yet, so `issue_num` values are recorded as
+placeholders and back-filled from each child's promotion receipt as preparation completes. The
+manifest is committed in final, resolved form before the kickoff artifact is written.
+
+## Complexity Assessment
+
+Assess each child feature's complexity band (`C1`-`C4`) using the `model_policy` scale and
+signals in `config/orchestration-routing.json`, and record the band with a short rationale in
+the planning checkpoint's `features[]` entries and in the epic narrative. The bands serve two
+purposes: they feed the epic-worthiness rationale, and they give each child orchestrator's own
+model-selection step a reviewed starting assessment.
+
+## Integration Branch Lifecycle
+
+1. Before any preparation delegation, create the integration branch off the tip of `main` if it
+   does not already exist: `git fetch origin main`,
+   `git checkout -b epic/<epic-slug>-integration origin/main`,
+   `git push -u origin epic/<epic-slug>-integration`.
+2. Commit the epic home (`epic.md`) to the integration branch before delegating preparation.
+3. All prepared child outputs fan in to the integration branch (see Fan-In below), so the
+   branch's final state is the complete, execution-ready epic plan.
+
+## Preparation-Mode Child Delegation
+
+Delegate one `Agent(orchestrator)` run per child feature. Because preparation produces documents
+and plans rather than code, dependency edges impose no build-order constraint: launch ALL child
+preparations concurrently (one message, N `Agent` calls, each `isolation: "worktree"` and
+`run_in_background: true`), branching each worktree from `origin/epic/<epic-slug>-integration`.
+For a dependent feature, include the upstream features' planned scope (spec/plan references or
+manifest excerpts) as context lines so its spec and plan cite the upstream contracts they will
+consume.
+
+Each delegation prompt includes the literal preparation-mode kickoff line:
+
+> `Preparation mode: true. route_id: preparation. epic_feature_folder: <epic-slug>. integration_branch: epic/<epic-slug>-integration. Perform promotion, research, feature documents (spec.md, user-story.md), atomic planning, and preflight clearance only. Atomic execution, PR authoring, and CI monitoring are out of scope for this run and are executed later by epic-orchestrator. After the atomic-executor preflight returns PREFLIGHT: ALL CLEAR, commit the feature folder and plan to the current branch, set out-of-scope step statuses to not-applicable, set next_step to S5_atomic_execution, and stop, reporting the plan-path and preflight status.`
+
+The prompt must also reference the child's target feature folder path once promotion assigns it,
+or the promotion inputs (potential entry path, short name) when it does not exist yet. The
+preparation-mode kickoff line deliberately omits the epic-mode marker (`Epic mode: true`) so the
+`enforce-epic-wave-barrier.ps1` deterrent, which gates execution-phase delegations, does not
+apply to preparation.
+
+### Child run contract (route_id: preparation)
+
+A preparation-mode `orchestrator` run:
+
+- Selects `route_id: preparation` (defined in `config/orchestration-routing.json`), whose
+  required receipts are `task-researcher`, `prd-feature`, `atomic-planner`, and
+  `atomic-executor` (preflight-only), the skills `orchestrate`,
+  `feature-promotion-lifecycle`, and `atomic-plan-contract`, and the promotion plus validator
+  MCP tools.
+- Runs promotion via the MCP surface, research, feature documents, atomic planning, and the
+  atomic-executor preflight (precondition validation only, per the orchestrate skill's R2
+  semantics), iterating plan revisions until `PREFLIGHT: ALL CLEAR`.
+- Terminates with `completed_steps` containing `S3_promotion` and `S4_atomic_planning`,
+  `next_step: "S5_atomic_execution"`, out-of-scope step statuses `not-applicable`, and
+  `blocked_reason: "none"`. The route's `requires_ci_gate: false` means the completion validator
+  demands no `ci_gate`/`pr_gate` evidence; the run must NOT assert `next_step: "complete"`.
+
+## Fan-In to the Integration Branch
+
+As each child preparation completes:
+
+1. Fetch the child worktree's branch and merge it into `epic/<epic-slug>-integration`. Prepared
+   outputs live in disjoint `docs/features/active/<feature>/` trees, so conflicts indicate a
+   decomposition defect; on conflict, halt fan-in and record blocked state rather than resolving
+   ad hoc.
+2. Back-fill the child's `issue_num` (and resolved `feature_folder`) into the epic manifest.
+3. Update the planning checkpoint's `features[]` entry (`preparation_status`, `plan_path`,
+   `preflight_status`).
+4. Remove the child worktree once its branch is merged.
+
+After the final fan-in, push the integration branch.
+
+## Kickoff Prompt Artifact
+
+After all features are prepared and committed, write the epic-orchestrator kickoff prompt to
+`artifacts/orchestration/epic-kickoff-<epic-slug>.md`, and commit a durable copy to
+`docs/features/epics/<epic-slug>/epic-kickoff.md` (the `artifacts/` tree is gitignored; the
+committed copy travels with the integration branch). The artifact contains:
+
+```markdown
+# Epic Kickoff: <epic-slug>
+
+Planned by epic-planner on <iso8601>. All child features are prepared: issues promoted, active
+folders created, research complete, spec/user-story written, atomic plans approved, preflight
+ALL CLEAR. Planning state: artifacts/orchestration/epic-planner-state.json (branch:
+epic/<epic-slug>-integration).
+
+## Invocation Prompt
+
+Run `/epic-run <epic-slug>` to execute this epic, or paste the prompt below.
+
+Use the epic-orchestrator subagent to execute the prepared epic at
+docs/features/epics/<epic-slug>/epic.md. The integration branch
+epic/<epic-slug>-integration already contains every prepared feature folder and approved atomic
+plan; child features resume at atomic execution from their committed plan-path rather than
+re-planning. Execute per the epic-orchestrate skill: wave-scheduled child orchestrator runs in
+isolated worktrees, merge-on-green fan-in to the integration branch, and the final
+integration-to-main PR.
+
+## Feature Summary
+
+| issue_num | feature_folder | wave | complexity | plan-path |
+| --- | --- | --- | --- | --- |
+| ... | ... | ... | ... | ... |
+```
+
+The `## Invocation Prompt` section is the exact text the user replays (from the main session,
+never from an `orchestrator` agent) to launch execution.
+
+## Checkpoint Handling
+
+Persist `artifacts/orchestration/epic-planner-state.json` after every completed step with the
+fields listed in `.claude/agents/epic-planner.md` (`## Checkpoint Persistence`). On resume,
+re-derive durable ground truth from `git branch`/`git worktree list --porcelain`, the epic
+manifest, and the prepared feature folders; treat the checkpoint's `next_step` as the resume
+pointer, not as a substitute for on-disk state.
+
+## Completion Report
+
+The final report to the user must include: the epic manifest path, one `plan-path:` line plus
+preflight status per feature, the integration branch name, and the kickoff artifact paths. End
+with the statement that execution has NOT started and will begin only when the user runs
+`/epic-run <epic-slug>` or replays the kickoff prompt.

package/resources/claude-customizations/.claude/skills/epic-run/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: epic-run
+description: Execute a previously planned epic by replaying the committed epic-kickoff artifact through the epic-orchestrator agent. Use after /epic-plan has prepared the epic (issues, folders, research, specs, atomic plans, preflight clearance) and the user is ready to execute end-to-end.
+argument-hint: "[epic-slug]"
+context: fork
+agent: epic-orchestrator
+---
+
+# Epic Run Skill
+
+A user invocation (`/epic-run <epic-slug>`) forks the `epic-orchestrator` agent to execute an
+epic that `epic-planner` has already prepared. The epic slug (or a path under
+`docs/features/epics/`) for this run is:
+
+$ARGUMENTS
+
+## Procedure
+
+1. Resolve the epic home. A bare slug resolves to `docs/features/epics/<epic-slug>/`; a path
+   argument resolves to its containing epic folder.
+2. Read the committed kickoff artifact at `docs/features/epics/<epic-slug>/epic-kickoff.md`.
+   - If the file does not exist, STOP without delegating anything and report that the epic has
+     no committed kickoff artifact: the user must run `/epic-plan` first (or, for an epic that
+     was authored manually, invoke `/epic-orchestrate <epic-manifest-path>` directly).
+3. Execute the kickoff artifact's `## Invocation Prompt` section as the epic objective, applying
+   the `epic-orchestrate` skill procedure and the `## Prepared-Epic Execution (epic-planner
+   Handoff)` section of `.claude/agents/epic-orchestrator.md`: reuse the existing integration
+   branch, and have each child `Agent(orchestrator)` delegation resume at atomic execution from
+   its committed `plan-path` rather than re-running promotion, research, or planning.
+4. Honor existing checkpoint state: if `artifacts/orchestration/epic-orchestrator-state.json`
+   already tracks this epic, resume per the `epic-orchestrate` skill's resume procedure instead
+   of restarting.
+
+## Scope
+
+This skill adds no procedure of its own beyond kickoff-artifact resolution; wave scheduling,
+the wave barrier, merge-on-green fan-in, worktree cleanup, `epic-status.md` maintenance, and
+the final integration-to-`main` PR are governed entirely by the `epic-orchestrate` skill.

package/resources/claude-customizations/.claude/skills/orchestrate/SKILL.md

@@ -6,7 +6,17 @@ argument-hint: "[objective]"
 
 # Orchestrate Skill
 
-This skill frames work for the already-active main session, which serves as the orchestrator runtime for end-to-end feature or bug delivery.
+This skill frames work for the already-active main session, which serves as the orchestrator runtime for end-to-end feature or bug delivery. Orchestration deliberately stays in the main session on user invocation (`/orchestrate <objective>`); the same procedure governs a delegated `Agent(orchestrator)` run from `epic-planner` or `epic-orchestrator`.
+
+## Invocation Argument
+
+When invoked as `/orchestrate`, the orchestration objective is:
+
+$ARGUMENTS
+
+A delegated `Agent(orchestrator)` run receives its objective in the delegation prompt instead.
+
+Perform the scale assessment first: if the objective is epic-scale (names an epic manifest or requires multiple independently mergeable features), stop before any delegation and direct the user to `/epic-plan` (planning) or `/epic-run` (executing a prepared epic), per `## Change Budget Routing` in `.claude/agents/orchestrator.md`.
 
 ## Prerequisites
 
@@ -77,9 +87,18 @@ After reading `artifacts/orchestration/orchestrator-state.json`, the main sessio
 
 The orchestrator does not perform deep implementation itself. It coordinates, tracks state, and enforces completion.
 
+## Preparation Mode
+
+A delegation prompt carrying the literal marker `Preparation mode: true` (issued by `epic-planner` per the `.claude/skills/epic-plan/SKILL.md` kickoff line) scopes the run to planning only:
+
+- **Route.** Select `route_id: preparation`. The route's routing-matrix entry requires receipts for `task-researcher`, `prd-feature`, `atomic-planner`, and `atomic-executor`; the skills `orchestrate`, `feature-promotion-lifecycle`, and `atomic-plan-contract`; and the promotion plus validator MCP tools.
+- **Scope.** Run promotion (MCP surface), research, feature documents (`spec.md`, `user-story.md`), atomic planning, and the atomic-executor preflight (precondition validation only, R2 semantics: iterate plan revisions until `PREFLIGHT: ALL CLEAR`). Atomic execution, PR authoring, CI monitoring, and feature review are out of scope and are executed later by `epic-orchestrator`.
+- **Terminal checkpoint.** Stop with `completed_steps` containing `S3_promotion` and `S4_atomic_planning`, `next_step: "S5_atomic_execution"`, out-of-scope step statuses set to `not-applicable`, and `blocked_reason: "none"`. Do NOT assert completion (`next_step: "complete"`, `S12_complete`, or a `completed` step8/9/10 status): the run has no PR or CI evidence, and the route's `requires_ci_gate: false` exempts it from `ci_gate` at the completion validator instead.
+- **Commit.** Commit the prepared feature folder and plan to the current branch (the worktree branch created off the epic integration branch) before stopping, and report the `plan-path` and preflight status in the final output.
+
 ## Model Selection
 
-Model selection is a second axis, strictly separate from `route`. `route` (`small | large | remediation | epic`) is deterministic and file-count driven; it governs `required_agents`, `required_skills`, and `required_mcp_tools` only. `route` is NOT an input to model selection anywhere. The sole feature-level input to the delegation model tier is a judgment-based `complexity_band` (`C1 | C2 | C3 | C4`). The authoritative values live in the `model_policy` block of `config/orchestration-routing.json`.
+Model selection is a second axis, strictly separate from `route`. `route` (`small | large | remediation | preparation | epic`) is deterministic — file-count driven for `small`/`large`, marker-driven for `preparation` (the `Preparation mode: true` kickoff line) and `epic`; it governs `required_agents`, `required_skills`, and `required_mcp_tools` only. `route` is NOT an input to model selection anywhere. The sole feature-level input to the delegation model tier is a judgment-based `complexity_band` (`C1 | C2 | C3 | C4`). The authoritative values live in the `model_policy` block of `config/orchestration-routing.json`.
 
 The two canonical, tested reference implementations express the formulas the orchestrator applies by judgment:
 

package/resources/claude-customizations/pack-manifests/core.json

@@ -7,6 +7,7 @@
     ".claude/agents/atomic-planner.md",
     ".claude/agents/commit-message.md",
     ".claude/agents/epic-orchestrator.md",
+    ".claude/agents/epic-planner.md",
     ".claude/agents/epic-review.md",
     ".claude/agents/feature-review.md",
     ".claude/agents/human-exception-runbook.md",
@@ -17,6 +18,7 @@
     ".claude/agents/task-researcher.md",
     ".claude/hooks/enforce-checkpoint-monotonic.ps1",
     ".claude/hooks/enforce-completion-consistency.ps1",
+    ".claude/hooks/enforce-epic-invocation-origin.ps1",
     ".claude/hooks/enforce-epic-merge-gate.ps1",
     ".claude/hooks/enforce-epic-wave-barrier.ps1",
     ".claude/hooks/enforce-epic-worktree-removal-gate.ps1",
@@ -49,6 +51,8 @@
     ".claude/skills/atomic-plan-contract/SKILL.md",
     ".claude/skills/commit-message/SKILL.md",
     ".claude/skills/epic-orchestrate/SKILL.md",
+    ".claude/skills/epic-plan/SKILL.md",
+    ".claude/skills/epic-run/SKILL.md",
     ".claude/skills/evidence-and-timestamp-conventions/SKILL.md",
     ".claude/skills/execute-hard-lock/SKILL.md",
     ".claude/skills/feature-promotion-lifecycle/SKILL.md",

package/resources/config/orchestration-routing.json

@@ -72,6 +72,27 @@
         "validate_orchestration_artifacts"
       ]
     },
+    "preparation": {
+      "description": "Epic preparation path driven by epic-planner: promotion, research, feature documents, atomic planning, and preflight clearance only. Atomic execution, PR authoring, and CI monitoring are out of scope and deferred to the epic execution phase, so this route requires no CI gate at completion.",
+      "requires_ci_gate": false,
+      "required_agents": [
+        "task-researcher",
+        "prd-feature",
+        "atomic-planner",
+        "atomic-executor"
+      ],
+      "required_skills": [
+        "orchestrate",
+        "feature-promotion-lifecycle",
+        "atomic-plan-contract"
+      ],
+      "required_mcp_tools": [
+        "new_potential_entry",
+        "potential_to_issue",
+        "new_active_feature_folder",
+        "validate_orchestration_artifacts"
+      ]
+    },
     "epic": {
       "description": "Epic path for scheduling a dependency graph of child features across parallel worktrees with fan-in via a shared integration branch.",
       "requires_pr_gate": true,