@danmoisan/drm-copilot-mcp 1.0.11 → 1.0.14

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,
@@ -22,10 +29,12 @@ Before proceeding, `epic-orchestrator` must:
 
 ## Epic Dependency Manifest
 
-The epic manifest is Markdown with YAML frontmatter, at
-`docs/features/epics/<epic-slug>/epic-plan.md`. The frontmatter carries the fields that must be
-parsed deterministically; the Markdown body below the frontmatter carries free-text epic
-narrative (goal, scope, non-goals) that is not machine-parsed.
+The epic manifest is the YAML frontmatter of the single epic home
+`docs/features/epics/<epic-slug>/epic.md`. `epic.md` is the merged source of truth: its
+frontmatter carries the fields that must be parsed deterministically, and the Markdown body
+below the frontmatter carries the single free-text epic narrative (goal, scope, non-goals,
+shared design, decomposition) that is not machine-parsed. `epic.md` is also the source from
+which the epic GitHub issue body is generated.
 
 Frontmatter schema:
 
@@ -34,19 +43,37 @@ Frontmatter schema:
 epic: <epic-slug>
 integration_branch: epic/<epic-slug>-integration
 created_at: <iso8601>
+# Optional additive SAFe-style intent block. Omit the whole block when unused; when
+# present, epic_type and business_outcome_hypothesis are required and
+# leading_indicators / nfrs are optional lists of strings.
+intent:
+  epic_type: <business | enabler>
+  business_outcome_hypothesis: <measurable outcome the epic is expected to move>
+  leading_indicators: [<early validation signal>, ...]
+  nfrs: [<non-functional requirement>, ...]
 features:
-  - feature_folder: <feature-folder-basename>
-    issue_num: <int>
-    depends_on: [<feature-folder-basename>, ...]
+  - issue_num: <int>
+    feature_folder: <resolvable-hint-basename>
+    depends_on: [<upstream-issue_num>, ...]
 ---
 ```
 
-- `feature_folder` is the canonical identifier: the exact active-feature-folder basename,
-  matching the vocabulary already used by the per-feature checkpoint's `feature-folder` field.
-- `depends_on` is an array of `feature_folder` values that must each already exist as another
-  entry in `features[]`. A `depends_on` entry that does not resolve to a defined `feature_folder`,
-  or a duplicate `feature_folder` value, is a malformed manifest and is rejected before epic
-  kickoff as a synthetic Blocking finding — `epic-orchestrator` does not guess.
+- `issue_num` is the primary key: the stable GitHub issue number for the child feature. The
+  DAG is keyed by `issue_num`, so it does not drift when a child is promoted from `active/` to
+  `completed/`.
+- `feature_folder` is a resolvable hint, not a stable identifier. It may resolve to a concrete
+  path under `docs/features/active/<basename>` or `docs/features/completed/<basename>`; a
+  lifecycle prefix is stripped to the basename during resolution.
+- `depends_on` is an array of `issue_num` values (legacy manifests may still use
+  `feature_folder` basenames). Each entry must resolve — via the union index of the
+  `issue_num` set plus the `feature_folder` set — to another entry in `features[]`. A
+  `depends_on` entry that does not resolve, or a duplicate `feature_folder` value, is a
+  malformed manifest and is rejected before epic kickoff as a synthetic Blocking finding —
+  `epic-orchestrator` does not guess.
+- The optional `intent` block is additive and presence-gated: when present it is validated
+  (`epic_type` in {business, enabler}, non-empty `business_outcome_hypothesis`, string-list
+  `leading_indicators` / `nfrs`); when absent, validation is byte-identical to a manifest
+  without it.
 
 ## Wave Assignment
 
@@ -137,10 +164,14 @@ When `epic-orchestrator` kicks off a feature with a non-empty `depends_on`, the
 includes one literal citation line per dependency, appended after the epic-mode kickoff line
 above:
 
-> `Upstream context for <feature_folder>: depends on <dep_feature_folder> (spec: docs/features/active/<dep_feature_folder>/spec.md — or docs/features/completed/<dep_feature_folder>/spec.md if already promoted to completed; plan: docs/features/active/<dep_feature_folder>/plan.<ts>.md; merged as PR #<dep_pr_number>, commit <dep_merge_commit_sha>, into <integration_branch>).`
+> `Upstream context for <issue_num>: depends on <dep_issue_num> (spec: <dep_resolved_folder>/spec.md; plan: <dep_resolved_folder>/plan.<ts>.md; merged as PR #<dep_pr_number>, commit <dep_merge_commit_sha>, into <integration_branch>).`
 
-`epic-orchestrator` resolves the concrete `<dep_...>` values from its own checkpoint's
-`features[]` records for each dependency before emitting the line, so the dependent feature's own
+`epic-orchestrator` resolves each dependency by its stable `issue_num` against its own
+checkpoint's `features[]` records, and resolves `<dep_resolved_folder>` to the dependency's
+concrete `feature_folder` path — under `docs/features/active/` or `docs/features/completed/`
+depending on the dependency's current lifecycle state at emit time — before emitting the line.
+Because the DAG is keyed by `issue_num`, no active→completed path-drift workaround is needed: the
+concrete path is resolved from the checkpoint's current state, so the dependent feature's own
 `orchestrator`/`atomic-planner` is told exactly which upstream artifacts are relevant rather than
 being expected to rediscover prior design decisions from the diff alone.
 
@@ -207,12 +238,13 @@ child worktree) issues `git worktree remove <worktree_path>`, gated by
 
 ## Documentation Maintenance Boundaries
 
-`epic-plan.md` (the manifest) and `epic-status.md` (a separate, epic-orchestrator-maintained
-status document) are kept distinct. `epic-plan.md`'s frontmatter is the human-authored, largely
-static input; automatic epic decomposition is out of scope, so this file is not repeatedly
-rewritten. `epic-orchestrator` instead maintains
-`docs/features/epics/<epic-slug>/epic-status.md`, regenerated (not hand-edited) from the epic
-checkpoint at each of the following boundaries, not only at final completion:
+`epic.md` (the merged manifest + narrative source of truth) and `epic-status.md` (a separate,
+epic-orchestrator-maintained status document) are kept distinct. `epic.md`'s frontmatter is the
+human-authored, largely static input; automatic epic decomposition is out of scope, so this
+file is not repeatedly rewritten. `epic-status.md` is a generated projection only: it is
+regenerated (never hand-authored) from the epic checkpoint and is never the source of the DAG.
+`epic-orchestrator` maintains `docs/features/epics/<epic-slug>/epic-status.md`, regenerated from
+the epic checkpoint at each of the following boundaries, not only at final completion:
 
 - Epic kickoff — initial status table seeded from the manifest (one row per feature: wave,
   status `not_started`).
@@ -229,12 +261,14 @@ checkpoint JSON remains the durable, machine-authoritative source.
 ## Epic-Level Checkpoint
 
 `artifacts/orchestration/epic-orchestrator-state.json` carries `objective`, `route_id: "epic"`,
-`epic_feature_folder`, `epic_manifest_path`, `epic_status_doc_path`, `integration_branch`,
+`epic_feature_folder`, `epic_manifest_path` (which points at
+`docs/features/epics/<epic-slug>/epic.md`), `epic_status_doc_path`, `integration_branch`,
 `completed_steps`, `next_step`, `last_updated`, `current_wave`, `waves[]`, `features[]`,
 `epic_merge_pr`, and the three receipt arrays (`delegation_receipts[]`, `skill_receipts[]`,
 `mcp_call_receipts[]`) — the full schema is defined in `spec.md` §6 of this feature. The
 `merge_status` enum is: `not_started`, `worktree_created`, `pr_open`, `ci_green`,
-`merge_conflict`, `blocked_conflict_loop_limit`, `merged`, `worktree_removed`.
+`merge_conflict`, `blocked_conflict_loop_limit`, `merged`, `worktree_removed`. The optional
+`intent` object (projection of the `epic.md` intent block) is validated presence-gated.
 
 Every field needed to re-derive state durably on resume (`worktree_path`, `branch_name`,
 `pr_number`, `merge_status`) is re-derivable from `git worktree list --porcelain`, `git branch`,

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/identify-session-id/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: identify-session-id
+description: Resolve the current Claude Code session id (the root transcript filename stem) without human input, using an ordered fallback chain, and report which source supplied it. Use before any workflow that needs the running session's id (for example show-my-agent-tree).
+allowed-tools:
+  - Read
+  - Bash
+---
+
+# Identify Session Id
+
+Resolve the current session's id — the root transcript filename stem under
+`~/.claude/projects/<encoded-workspace>/` — without asking the human. Try the
+sources in order and stop at the first that yields a non-empty id. Always
+report which source was used.
+
+## Resolution Order
+
+1. **Environment variable (primary).** Read `CLAUDE_SESSION_ID` from the
+   environment with a single command, e.g.:
+   - Bash: `printf '%s' "$CLAUDE_SESSION_ID"`
+   - pwsh: `pwsh -NoProfile -Command 'Write-Output $env:CLAUDE_SESSION_ID'`
+
+   This variable is provisioned by the SessionStart hook
+   `.claude/hooks/persist-session-id.ps1` through the `CLAUDE_ENV_FILE`
+   channel. If it is non-empty, use it and report source `env:CLAUDE_SESSION_ID`.
+
+2. **State file (secondary).** Read `.claude/state/current-session-id`
+   (written by the same hook when `CLAUDE_ENV_FILE` is unset). If it exists and
+   is non-empty, use its trimmed contents and report source
+   `.claude/state/current-session-id`.
+
+3. **Newest transcript (tertiary heuristic).** List the root `*.jsonl` files
+   directly under `~/.claude/projects/<encodeWorkspacePath(cwd)>/` (the encoding
+   replaces every path separator and `:` with `-`), pick the one with the
+   newest modification time, and use its filename stem (without `.jsonl`).
+   Report source `newest-mtime transcript` and note that this heuristic can
+   pick the wrong sibling only when multiple concurrent sessions share one
+   workspace path.
+
+## Output
+
+Report the resolved session id and the source that supplied it, for example:
+`session_id = <id> (source: env:CLAUDE_SESSION_ID)`. If every source is empty,
+state that the session id could not be resolved and which sources were checked.

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/.claude/skills/show-my-agent-tree/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: show-my-agent-tree
+description: Render the current session's subagent call tree and print it in the assistant reply. Use when the user asks to "show my agent tree" or otherwise wants to see the subagent hierarchy of the running session.
+allowed-tools:
+  - Read
+  - Bash
+  - mcp__drm-copilot__render_subagent_tree
+---
+
+# Show My Agent Tree
+
+Render the subagent call tree for the current session and print it directly in
+the assistant reply. This works identically in normal turns and in `/btw`
+side-conversations and needs no VS Code host API.
+
+## Flow
+
+1. **Resolve the session id.** Follow the `identify-session-id` skill to obtain
+   the current session id and note which source supplied it.
+
+2. **Call the MCP tool.** Invoke `mcp__drm-copilot__render_subagent_tree` with:
+   - `session_id`: the id resolved in step 1.
+   - `workspace_root`: an explicit absolute path to the current workspace root
+     (do not rely on the tool's default; pass it explicitly).
+
+   On success the tool returns `ok: true`, a `summary` naming the session id
+   and resolved transcript path, and a `rendered_tree` string.
+
+3. **Print the tree.** Output the `rendered_tree` value in the assistant reply
+   inside a fenced code block, so the hierarchy is legible. Include the
+   `summary` line above it for context.
+
+## Error Handling
+
+- If the tool returns `ok: false`, report the `summary` verbatim. An unknown
+  session id names the searched directories; a malformed session id names the
+  validation rule (`^[0-9A-Za-z-]{8,64}$`).
+- If `identify-session-id` cannot resolve an id, report that and do not call
+  the tool.

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",
@@ -28,6 +30,7 @@
     ".claude/hooks/enforce-pr-author-skill.ps1",
     ".claude/hooks/enforce-prd-feature-before-planner.ps1",
     ".claude/hooks/enforce-promotion-mcp-only.ps1",
+    ".claude/hooks/persist-session-id.ps1",
     ".claude/hooks/validate-bash.ps1",
     ".claude/hooks/validate-executor-output.ps1",
     ".claude/hooks/validate-feature-review-coverage.ps1",
@@ -48,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",
@@ -55,6 +60,7 @@
     ".claude/skills/fill-feature-docs/SKILL.md",
     ".claude/skills/human-exception-runbook/example.runbook.md",
     ".claude/skills/human-exception-runbook/SKILL.md",
+    ".claude/skills/identify-session-id/SKILL.md",
     ".claude/skills/make-skill-template/SKILL.md",
     ".claude/skills/orchestrate/SKILL.md",
     ".claude/skills/policy-audit-template-usage/SKILL.md",
@@ -67,6 +73,7 @@
     ".claude/skills/review-epic/SKILL.md",
     ".claude/skills/review-feature/SKILL.md",
     ".claude/skills/review-staged/SKILL.md",
+    ".claude/skills/show-my-agent-tree/SKILL.md",
     ".claude/skills/skill-canonical-location-audit/SKILL.md",
     ".claude/skills/translate-copilot-to-claude/SKILL.md",
     ".claude/skills/update-status/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,

package/resources/feature-templates/epic/epic-status.md

@@ -0,0 +1,20 @@
+<!--
+  GENERATED FILE — DO NOT HAND-AUTHOR.
+
+  epic-status.md is a generated projection of the epic checkpoint
+  (artifacts/orchestration/epic-orchestrator-state.json). It is regenerated by
+  the epic-orchestrator agent at each lifecycle boundary (epic kickoff, every
+  feature merge_status change, each wave transition, and final integration
+  merge). It is never the source of the dependency DAG and must never be edited
+  by hand — the manifest in epic.md and the epic checkpoint JSON are the
+  authoritative sources.
+-->
+
+# <epic-name> - Epic Status (generated)
+
+This document is regenerated from the epic checkpoint and must not be
+hand-authored. Any manual edit will be overwritten on the next regeneration.
+
+| feature_folder | issue_num | wave_number | merge_status | pr_url | merge_commit_sha |
+| --- | --- | --- | --- | --- | --- |
+| _(populated on epic kickoff from the manifest, then updated in place)_ | | | | | |