@danmoisan/drm-copilot-mcp 1.0.13 → 1.0.15

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/codex-and-agents-customizations/.agents/skills/architecture-boundaries/SKILL.md

@@ -4,7 +4,6 @@ description: Architecture boundary enforcement rules for the No-COM architecture
 paths:
   - "**/*.ts"
   - "**/*.cs"
-description: Architecture boundary enforcement rules for the No-COM architecture.
 ---
 
 # Converted rule

package/resources/codex-and-agents-customizations/.agents/skills/codex-model-routing/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: codex-model-routing
+description: Resolve and validate the deterministic Codex topology plus the exact deployment agent, model slug, and reasoning effort. Use before spawning routed Codex workers, when scope or an orchestration ceiling changes, when resuming a delegating checkpoint, or when validating Codex topology and model receipts.
+---
+
+# Codex Model Routing
+
+Keep model selection independent from the production-file-count route. File count
+selects the engineer/orchestrator topology; this skill selects the exact deployed
+agent profile.
+
+## Resolve topology first
+
+1. Record the implementation languages, estimated production and test file counts,
+   execution context, and any cross-cutting marker.
+2. Run the canonical topology resolver before choosing a logical agent:
+
+   ```powershell
+   poetry run python -m scripts.dev_tools.resolve_codex_topology `
+     --language <python|powershell|csharp|typescript> `
+     --production-file-count <count> `
+     --test-file-count <count> `
+     --execution-context <context>
+   ```
+
+   Add `--cross-cutting` when that route marker applies. Root epic entry instead
+   supplies `--root-persona epic-planner` or `--root-persona epic-orchestrator`.
+3. Persist the returned object in `codex_topology_receipts[]` with a non-empty
+   `phase` before delegation.
+4. Use the returned `logical_agent` as the input to the model resolver below.
+   Do not replace a small typed-engineer result with an orchestrator, or an
+   orchestrator result with a typed engineer.
+
+Production-file count alone selects the small versus large topology: Python and
+C# allow up to 3 production files, and PowerShell allows up to 2. The recorded
+test-file caps govern typed-engineer execution batches without changing topology.
+TypeScript has no canonical direct-mode budget and therefore fails closed to the
+large orchestrator topology. Epic children always use the orchestrator topology;
+epic root personas are forced independently of file count.
+
+## Resolve a deployment
+
+1. Read `config/orchestration-routing.json` and use its
+   `codex_model_policy` block without substituting aliases.
+2. Assess `complexity_band` (`C1`-`C4`) using the shared complexity scale and
+   deterministic floor signals. C4 remains judgment-only.
+3. Record `execution_context` as one of `standalone`,
+   `epic_preparation_child`, or `epic_execution_child`.
+4. Record the monotonic `orchestration_complexity_ceiling`. It may increase as
+   scope is discovered, but it must not decrease during the run. When it rises,
+   add `ceiling_transition` with exact `from`, `to`, and the non-empty unique
+   `affected_delegation_ids` that must be re-resolved under the higher ceiling.
+5. Run the canonical resolver:
+
+   ```powershell
+   poetry run python -m scripts.dev_tools.resolve_codex_deployment `
+     --logical-agent <agent> `
+     --complexity-band <C1|C2|C3|C4> `
+     --execution-context <context> `
+     --orchestration-complexity-ceiling <C1|C2|C3|C4>
+   ```
+
+6. Persist the returned object in `codex_model_routing_receipts[]` with a
+   non-empty `phase` before spawning the returned `deployment_agent`.
+7. Spawn the generated agent profile. Do not spawn the base alias and claim that
+   a different model was selected.
+
+The route name `feature-review` resolves to the native
+`feature-reviewer-<profile>` agent family; retain `feature-review` as the
+receipt's logical agent name.
+
+## Fixed routing outcomes
+
+- C1: `gpt-5.6-luna`, low reasoning.
+- C2: `gpt-5.6-terra`, medium reasoning.
+- C3 standalone with a C3 ceiling: `gpt-5.6-terra`, high reasoning.
+- C3 in either epic-child context, or C3 under a C4 ceiling:
+  `gpt-5.6-sol`, high reasoning through the `-c3-elevated` profile.
+- C4: `gpt-5.6-sol`, max reasoning.
+- `epic-planner` and `epic-orchestrator`: always `gpt-5.6-sol`, ultra
+  reasoning.
+
+If the exact model is unavailable, record `model_unavailable`, leave the work
+incomplete, and request a policy change. Do not silently fall back.
+
+## Validation
+
+Before accepting delegated results or reporting completion, validate the
+checkpoint with the Codex routing gate:
+
+```powershell
+poetry run python -m scripts.dev_tools.validate_orchestration_artifacts `
+  orchestrator-state artifacts/orchestration/orchestrator-state.json `
+  --require-codex-topology `
+  --require-codex-model-routing
+```
+
+For epic execution use `epic-orchestrator-state` with the same flag. The MCP
+`validate_orchestration_artifacts` surface is the authoritative completion gate
+when available.

package/resources/codex-and-agents-customizations/.agents/skills/codex-model-routing/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Codex Deployment Routing"
+  short_description: "Route Codex topology and model profiles"
+  default_prompt: "Resolve the deterministic topology and exact Codex deployment profile for this work."

package/resources/codex-and-agents-customizations/.agents/skills/epic-orchestrate/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: epic-orchestrate
+description: Execute a manually authored multi-feature epic through deterministic waves, isolated worktrees, integration-branch fan-in, and a final integration PR.
+---
+
+# Epic Orchestrate Skill
+
+Use this manual-manifest compatibility entry only from the root session. The root session must
+delegate the supplied manifest or slug to the project custom agent `epic-orchestrator`; an
+ordinary `orchestrator` is prohibited from doing so. A committed planner kickoff is optional for
+this entry path.
+
+Use the epic manifest path or slug supplied in the invoking user request.
+
+## Prerequisites
+
+Read `AGENTS.md`, applicable language policies, `config/orchestration-routing.json`, and any
+existing `artifacts/orchestration/epic-orchestrator-state.json` checkpoint before acting.
+
+## Manifest Contract
+
+The source of truth is `docs/features/epics/<epic-slug>/epic.md`. Its YAML frontmatter is:
+
+```yaml
+---
+epic: <epic-slug>
+integration_branch: epic/<epic-slug>-integration
+created_at: <iso8601>
+intent: # optional as a whole
+  epic_type: <business | enabler>
+  business_outcome_hypothesis: <non-empty measurable outcome>
+  leading_indicators: [<string>, ...]
+  nfrs: [<string>, ...]
+features:
+  - issue_num: <int>
+    feature_folder: <resolvable-hint-basename>
+    depends_on: [<upstream-issue_num>, ...]
+---
+```
+
+`issue_num` is the stable primary key. `feature_folder` is a resolvable hint under `active/` or
+`completed/`. Every dependency must resolve against the union of issue numbers and legacy folder
+basenames. Reject duplicate folders, unresolved dependencies, malformed optional intent, and
+cycles before kickoff.
+
+## Wave Computation
+
+Use longest-path layering:
+
+```text
+wave(f) = 0                                      when depends_on(f) is empty
+wave(f) = 1 + max(wave(d) for d in depends_on(f)) otherwise
+```
+
+Use `scripts/dev_tools/epic_wave_computation.py` as the tested reference. Serialize features
+within each wave lexicographically by folder, without changing wave membership.
+
+## Entry Paths
+
+- Prepared path (`epic-run`): require and validate `epic-kickoff.md`, reuse the recorded
+  integration branch, and resume each child at atomic execution.
+- Manual path (`epic-orchestrate`): validate the manifest and create the integration branch when
+  absent. A kickoff artifact is not required.
+
+## Integration Branch and Child Worktrees
+
+Create a missing integration branch from current `origin/main` and push it. Before each wave,
+fetch the current remote integration tip. Create every child worktree from that tip, never from
+`main`, and set each feature PR base explicitly to the integration branch.
+
+Launch all ready children in one bounded parallel wave. Before each launch, persist the
+epic-child topology receipt, reviewed complexity assessment, delegation receipt, and Codex
+model-routing receipt with the same `delegation_id`, then select the generated deployment agent.
+C3 epic children use the elevated Sol/High profile. The child prompt contains:
+
+> `Epic mode: true. epic_feature_folder: <epic-slug>. integration_branch: epic/<epic-slug>-integration. epic_checkpoint_path: artifacts/orchestration/epic-orchestrator-state.json. PR base branch MUST be <integration_branch>, not main; pass --base <integration_branch> to gh pr create.`
+
+For prepared epics, also provide the committed `plan-path` and state that the child resumes at
+atomic execution. For each dependency, include its concrete spec, plan, PR, merge SHA, and target
+branch as upstream context.
+
+Do not use native `spawn_agent` for worktree children. For each wave, write an immutable launch
+specification under `artifacts/orchestration/epic-child-launches/<wave-id>/` and invoke
+`.codex/scripts/launch-epic-child-wave.ps1` with `checkpoint_kind: "epic-orchestrator"`, the
+current wave number, checkpoint path, integration branch, `max_parallel_features`, and exact
+generated profile values for every child. Monitor the durable wave status and record each child
+launch receipt/status path. A missing session id, nonzero exit, receipt mismatch, or incomplete
+wave status blocks the wave barrier.
+
+The JSON specification requires `schema_version: 1`, `wave_id`, `checkpoint_kind`,
+`checkpoint_path`, `integration_branch`, `wave_number`, `max_parallel_features`, and `launches`.
+Each launch requires `launch_id`, `delegation_id`, `feature_folder`, positive `issue_num`,
+`deployment_agent`, `model`, `model_reasoning_effort`, `permissions`,
+`execution_context: "epic_execution_child"`, canonical absolute `worktree_path`, `branch_name`,
+and the exact prompt. Invoke it as:
+
+```powershell
+pwsh -NoProfile -File .codex/scripts/launch-epic-child-wave.ps1 -LaunchSpecPath <spec-path> -MaxParallel <max_parallel_features>
+```
+
+Parse the returned JSON `status_path`. The status file is shared by the wave; every child has its
+own immutable receipt but references the same `wave.<wave_id>.status.json`.
+
+## Wave Barrier
+
+Do not start wave N+1 until every dependency edge is durably `merged` or `worktree_removed`.
+Reconcile this state using Git worktrees, branches, and live PR state on resume. The Codex
+mutation hook is a per-child deterrent; the epic-state validator is the retrospective,
+authoritative backstop.
+
+## Fan-In and Conflict Handling
+
+Each child owns its implementation, review, PR, CI-green gate, and merge into the integration
+branch. A merge conflict enters that child's existing remediation loop with a blocking
+`remediation-inputs.<timestamp>.md`. After three unresolved passes, record
+`blocked_conflict_loop_limit` and stop that edge. The epic agent must not resolve child conflicts
+locally.
+
+## Worktree Cleanup
+
+After the child merge SHA is recorded and the epic checkpoint mirrors `merge_status: "merged"`,
+remove its worktree. The worktree-removal hook denies removal before the matching feature is
+`merged` or `worktree_removed`. Record `worktree_removed_at` after success.
+
+## Model and Deployment Policy
+
+Route selection and model selection are independent. The deterministic file-count or marker
+route selects topology; the C1-C4 assessment selects a checked-in Codex deployment profile.
+
+- C1: `gpt-5.6-luna`, low.
+- C2: `gpt-5.6-terra`, medium.
+- standalone C3 with ceiling C3: `gpt-5.6-terra`, high.
+- epic C3 or C3 with a C4 sibling: `gpt-5.6-sol`, high.
+- C4: `gpt-5.6-sol`, max.
+- `epic-orchestrator`: `gpt-5.6-sol`, ultra.
+
+Persist the topology and model-routing receipts before every child or `pr-author` delegation. The
+deployed agent type and actual model must match its receipts and start attestation. If the
+required profile is unavailable, record `model_unavailable` and stop; do not fall back silently.
+
+## Status Projection and Checkpoint
+
+Regenerate `docs/features/epics/<epic-slug>/epic-status.md` from the checkpoint at kickoff, each
+merge-status transition, each wave transition, and each final-PR transition. Never treat the
+status document as the DAG source.
+
+Persist `artifacts/orchestration/epic-orchestrator-state.json` with `objective`, `route_id:
+"epic"`, epic folder/manifest/status paths, integration branch, completed and next steps,
+timestamps, bounded `max_parallel_features`, current wave, waves, features and lifecycle
+timestamps, final PR, complexity/model receipts, and required agent/skill/MCP receipts. Each
+launched feature records issue/folder, unique branch/worktree, delegation receipt/id,
+delegation-bound model receipt, and launch receipt/status paths.
+
+On resume, reconcile the checkpoint against `git worktree list --porcelain`, branch state, and
+`gh pr view --json state,mergedAt,headRefOid` before continuing.
+
+## Final Integration PR
+
+After every child is merged or its worktree removed, delegate final PR authoring to the routed
+`pr-author` profile, refresh PR context through the MCP surface, run the CI-green procedure,
+record the current head SHA and successful conclusion, and merge the integration branch to
+`main` only through the merge gate.
+
+## Completion
+
+Do not report completion until every feature is `merged` or `worktree_removed`, the final PR is
+merged with its merge SHA recorded, `epic-status.md` reflects that state, acceptance criteria are
+checked, and the MCP validator passes `epic-orchestrator-state` with `require_complete: true`.
+Require both `require_codex_topology: true` and `require_codex_model_routing: true` on that final
+validation call.

package/resources/codex-and-agents-customizations/.agents/skills/epic-plan/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: epic-plan
+description: Scope and prepare a multi-feature epic end-to-end before execution through the Codex epic-planner agent.
+---
+
+# Epic Plan Skill
+
+Use this skill only from the root session. The root session must delegate the supplied objective
+to the project custom agent `epic-planner`; it must not execute this procedure locally or route it
+through `orchestrator`. The root-invocation hook records the authorization receipt consumed when
+`epic-planner` starts.
+
+Use the objective or existing manifest path supplied in the invoking user request.
+
+Planning ends after every child feature has completed promotion, research, feature documents,
+atomic planning, and preflight clearance. Atomic execution, PR authoring, feature execution
+review, and CI monitoring are not part of this skill.
+
+## Prerequisites
+
+Before proceeding, `epic-planner` must read `AGENTS.md`, the applicable language policies under
+`.agents/skills/`, `config/orchestration-routing.json`, and any existing
+`artifacts/orchestration/epic-planner-state.json` checkpoint.
+
+## Epic-Worthiness Gate
+
+The objective warrants an epic only when both conditions hold:
+
+1. It decomposes into at least two independently mergeable child features, each with its own
+   issue, active feature folder, and eventual PR.
+2. At least one child exceeds, or the combined work clearly exceeds, one practical large-path
+   feature budget.
+
+When either condition fails, record `epic_worthiness.verdict: "non_epic"`, state the feature-count
+and change-budget rationale, and offer a single root-session `orchestrator` delegation. Do not
+create epic scaffolding unless the user explicitly overrides the verdict.
+
+## Decomposition and Wave Design
+
+For an epic-worthy objective:
+
+1. Define `docs/features/epics/<epic-slug>/` and author `epic.md` using the manifest schema in
+   `epic-orchestrate`.
+2. Record goal, scope, non-goals, shared design, acceptance criteria, decomposition rationale,
+   production-file estimates, and integration risks.
+3. Add `depends_on` edges only for real upstream contracts.
+4. Compute execution waves with the longest-path formula in
+   `scripts/dev_tools/epic_wave_computation.py`; unresolved references and cycles block
+   preparation.
+5. Assess each child as C1-C4 using the central policy. Record the assessed band, rationale,
+   deployment agent, model, reasoning effort, and the monotonic orchestration complexity ceiling.
+6. Set `max_parallel_features` to an integer from 1 through 8. Use the routing-policy default of
+   4 unless repository or user constraints require a lower value.
+
+Child issue numbers may be placeholders only while the draft manifest is being decomposed.
+Before creating child worktrees, promote every child through the worktree-aware MCP lifecycle,
+backfill the final positive `issue_num` and active `feature_folder`, commit and push that resolved
+manifest, and persist the promotion receipts. Launch specifications and their immutable receipts
+must never use placeholders.
+
+## Integration Branch
+
+Create or reuse `epic/<epic-slug>-integration` from `origin/main`, push it, and commit the epic
+home before preparation. All prepared child outputs must fan into this branch.
+
+## Concurrent Preparation
+
+Place all child preparations in one preparation batch, regardless of execution-wave
+dependencies. Each child runs in an isolated worktree branched from the current
+`origin/epic/<epic-slug>-integration` tip. Dependency context is supplied for planning, but it
+does not serialize preparation. The batch launcher enforces `max_parallel_features`; excess
+children remain queued in the same batch rather than being divided by execution wave.
+
+Before each child starts, persist its epic-child topology receipt, complexity assessment,
+delegation receipt, and Codex model-routing receipt. The model receipt must carry the same
+`delegation_id` as the delegation receipt.
+
+Do not use native `spawn_agent` for a worktree child because that API does not bind the child to
+the prepared worktree. Write one immutable launch specification under
+`artifacts/orchestration/epic-child-launches/<batch-id>/` and invoke
+`.codex/scripts/launch-epic-child-wave.ps1`. Use `checkpoint_kind: "epic-planner"`,
+`wave_number: 0`, the planner checkpoint path, integration branch, bounded maximum, and one
+launch record per child. Every record supplies the unique launch/delegation ids, prepared
+worktree and branch, generated `orchestrator-cN` profile, exact model/reasoning/permissions, and
+prompt. C3 epic children use the elevated Sol/High profile. Monitor the returned durable status
+path; a nonzero child exit or missing completion status blocks fan-in.
+
+The launch specification schema is:
+
+```json
+{
+  "schema_version": 1,
+  "wave_id": "<safe-preparation-batch-id>",
+  "checkpoint_kind": "epic-planner",
+  "checkpoint_path": "artifacts/orchestration/epic-planner-state.json",
+  "integration_branch": "epic/<epic-slug>-integration",
+  "wave_number": 0,
+  "max_parallel_features": 4,
+  "launches": [
+    {
+      "launch_id": "<unique-id>",
+      "delegation_id": "<unique-id>",
+      "feature_folder": "<final-active-feature-folder>",
+      "issue_num": 123,
+      "deployment_agent": "orchestrator-c3-elevated",
+      "model": "gpt-5.6-sol",
+      "model_reasoning_effort": "high",
+      "permissions": "orchestrator-workspace",
+      "execution_context": "epic_preparation_child",
+      "worktree_path": "<canonical-absolute-path>",
+      "branch_name": "<child-preparation-branch>",
+      "prompt": "<preparation prompt>"
+    }
+  ]
+}
+```
+
+Write it under `artifacts/orchestration/epic-child-launches/<batch-id>/`, then run:
+
+```powershell
+pwsh -NoProfile -File .codex/scripts/launch-epic-child-wave.ps1 -LaunchSpecPath <spec-path> -MaxParallel <max_parallel_features>
+```
+
+Parse the returned JSON and persist its shared `status_path`. Every worktree must be a clean Git
+worktree of this repository on the checkpoint branch. Its committed `.codex/`, `.agents/`,
+`AGENTS.md`, routing configuration, and selected profile must match the trusted integration
+source; the launcher rejects drift before starting Codex.
+
+Every child prompt must contain this literal line:
+
+> `Preparation mode: true. route_id: preparation. epic_feature_folder: <epic-slug>. integration_branch: epic/<epic-slug>-integration. Reuse and verify the completed promotion receipt, then perform research, feature documents (issue.md, 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 research_path, plan-path, preflight_evidence_path, and the exact preflight status.`
+
+The line intentionally omits `Epic mode: true`. For dependent children, also cite the upstream
+manifest scope, specification, and planned contract.
+
+## Preparation Route Contract
+
+Each child selects the exact `preparation` route from the central routing configuration:
+
+- required agents, in configured order: `task-researcher`, `prd-feature`, `atomic-planner`,
+  `atomic-executor`;
+- required skills: `orchestrate`, `feature-promotion-lifecycle`, `atomic-plan-contract`;
+- required MCP operations: `new_potential_entry`, `potential_to_issue`,
+  `new_active_feature_folder`, `validate_orchestration_artifacts`;
+- mandatory completed phases: `S3_promotion`, `S4_atomic_planning`;
+- terminal `next_step`: `S5_atomic_execution`;
+- execution-through-CI statuses: `not-applicable`;
+- `blocked_reason`: `none`;
+- `requires_ci_gate`: the literal JSON Boolean `false`.
+
+Promotion must use worktree-aware MCP calls and receipts. A child must not claim feature
+completion, create a PR, execute the atomic plan, or monitor CI.
+
+## Fan-In
+
+As each preparation finishes:
+
+1. Merge the child preparation branch into the integration branch.
+2. Treat any conflict as a decomposition defect: abort fan-in, record blocked state, and do not
+   resolve the conflict ad hoc.
+3. Backfill `issue_num` and `feature_folder` in `epic.md`.
+4. Record `preparation_status: "prepared"`, `research_path`, `plan_path`,
+   `preflight_evidence_path`, and `preflight_status: "PREFLIGHT: ALL CLEAR"` in the planner
+   checkpoint. `research_path` must be under `artifacts/research/` or inside the feature folder.
+   Each child references its immutable receipt and the shared `wave.<wave_id>.status.json` path.
+5. Remove the worktree only after its preparation branch is merged.
+
+Push the integration branch after final fan-in.
+
+There is no mid-planning approval pause. The planner completes promotion, research, feature
+documents, atomic planning, and preflight before stopping at the user execution boundary.
+
+## Execution-Readiness Gate
+
+Do not emit a kickoff until the manifest is valid, the checkpoint has a forced `epic-planner`
+topology receipt, and every child has a promoted issue, active folder, `issue.md`, research,
+`spec.md`, `user-story.md`, approved atomic plan, epic-preparation topology receipt,
+delegation-bound model-routing receipt, successful launcher receipt/status, `PREFLIGHT: ALL
+CLEAR` evidence, and a pushed preparation commit. The durable and ignored kickoff copies must be
+byte-identical; the manifest, durable kickoff, plans, and planning commits must pass the
+repository-aware readiness validator without worktree drift.
+
+Invoke `validate_orchestration_artifacts` for `epic-planner-state` with
+`require_ready_for_execution: true` and the explicit workspace root. Do not write or delegate the
+kickoff until this canonical gate succeeds.
+
+## Kickoff Artifacts
+
+Write the ignored copy to `artifacts/orchestration/epic-kickoff-<epic-slug>.md` and commit the
+durable copy at `docs/features/epics/<epic-slug>/epic-kickoff.md`:
+
+```markdown
+# Epic Kickoff: <epic-slug>
+
+Planned by epic-planner on <iso8601>. All child features are prepared. 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. Reuse epic/<epic-slug>-integration. Every child resumes
+at atomic execution from its committed plan-path; do not repeat promotion, research, feature
+documents, planning, or preflight.
+
+## Feature Summary
+
+| issue_num | feature_folder | wave | complexity | plan-path |
+| --- | --- | --- | --- | --- |
+| ... | ... | ... | ... | ... |
+```
+
+The baseline artifact shape is authoritative. An optional integrity block may record the
+planning commit and plan hashes, but `epic-run` must derive absent integrity values from Git.
+
+## Checkpoint and Completion
+
+Persist `artifacts/orchestration/epic-planner-state.json` after every completed step with:
+`objective`, epic folder and manifest, integration branch, worthiness verdict and rationale, the
+bounded `max_parallel_features`, forced root `topology_receipt`, and kickoff path. Each feature
+records issue/folder/dependencies/wave/complexity, `research_path`, `plan_path`, optional
+`preflight_evidence_path`, preparation/preflight state, branch/worktree, topology receipt,
+delegation receipt, delegation-bound model receipt, launch receipt/status paths, and planning
+commit/hash when declared. Also record `completed_steps`, `next_step`, and `last_updated`.
+
+The successful terminal result is `EPIC_EXECUTION_READY`. The final report lists the manifest,
+integration branch, both kickoff paths, and one `plan-path:` and preflight-status line per child.
+It must state that execution has not started and starts only after a later root invocation of
+`epic-run`.

package/resources/codex-and-agents-customizations/.agents/skills/epic-run/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: epic-run
+description: Execute a previously prepared epic by resolving its committed kickoff artifact and delegating it to the Codex epic-orchestrator agent.
+---
+
+# Epic Run Skill
+
+Use this skill only from the root session. The root session must resolve the committed kickoff
+artifact and delegate its invocation prompt to the project custom agent `epic-orchestrator`.
+The root-invocation hook records the authorization receipt consumed when that agent starts.
+
+Use the epic slug or path supplied in the invoking user request.
+
+## Procedure
+
+1. Resolve a bare slug to `docs/features/epics/<epic-slug>/`; resolve a supplied path to its
+   containing epic home.
+2. Require `docs/features/epics/<epic-slug>/epic-kickoff.md`.
+   - If it is absent, stop before delegation. Direct the user to run `epic-plan` first or, for a
+     manually authored epic, invoke `epic-orchestrate <manifest-path>`.
+3. Validate the kickoff's `## Invocation Prompt`, manifest reference, integration branch,
+   per-feature plan paths, preflight evidence, and current Git state. Derive optional missing
+   hashes from Git; fail closed on actual drift.
+   Invoke `validate_orchestration_artifacts` for `epic-planner-state` with
+   `require_ready_for_execution: true` and the explicit workspace root. Do not delegate until
+   that canonical repository-aware gate succeeds.
+4. Delegate the invocation prompt to `epic-orchestrator` and apply `epic-orchestrate`.
+5. Reuse the existing integration branch. Every child resumes at atomic execution from its
+   committed plan path. Do not repeat promotion, research, feature documents, planning, or
+   preflight.
+6. If `artifacts/orchestration/epic-orchestrator-state.json` already tracks this epic, resume from
+   its durable `next_step` instead of restarting.
+7. Worktree children must be launched through `.codex/scripts/launch-epic-child-wave.ps1`; do
+   not replace the launcher with native `spawn_agent`.
+8. Copy the validated planner checkpoint's `max_parallel_features` into the epic-orchestrator
+   checkpoint before constructing the first execution launch specification.
+
+Wave scheduling, fan-in, worktree cleanup, `epic-status.md`, final PR creation, CI validation,
+and completion are governed entirely by `epic-orchestrate`.