[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M754QANJHTDNFQQ0F6Z8NW9Z":3,"skill-same:01M754QANJHTDNFQQ0F6Z8NW9Z":59},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":30,"commitSha":31,"skillDirectory":32,"forksCount":33,"repositoryHtmlUrl":34,"repositoryHomepageUrl":6,"ownerHtmlUrl":35,"ownerBlogUrl":36,"ownerDescription":37,"updatedAt":38,"install":39,"resources":52},"01M754QANJHTDNFQQ0F6Z8NW9Z","x-internal-build-epic-plan",null,"Builds the canonical ExecutionPlan for an epic (Phase 0\u002F0.5 carve-out of x-implement-epic): loads epic-XXXX.md, IMPLEMENTATION-MAP.md, and every story-*.md; constructs the inter-story dependency DAG; runs Kahn's algorithm with cycle detection; optionally computes a file-overlap matrix (mode=parallel) and the critical path; then renders ai\u002Fepics\u002Fepic-XXXX\u002Fepic-execution-plan.md via x-internal-write-report using the _TEMPLATE-EPIC-EXECUTION-PLAN.md template. Emits a stable JSON envelope on stdout for orchestrator consumption. Sixth skill in the x-internal-* convention and the third under internal\u002Fplan\u002F (after x-internal-load-story-context and x-internal-build-story-plan).","review-bench\u002Federcnj_ia-dev-environment","review-bench","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F286778065?v=4","01M7517F9NTEPDZDAXJBR30FWT","ReviewBench","01M7517FAC9F4P7TGWCNJ8VYVW",0,"MIT","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring-fintech-pci\u002F.claude\u002Fskills\u002Fx-internal-build-epic-plan\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: x-internal-build-epic-plan\ndescription: \"Builds the canonical ExecutionPlan for an epic (Phase 0\u002F0.5 carve-out of x-implement-epic): loads epic-XXXX.md, IMPLEMENTATION-MAP.md, and every story-*.md; constructs the inter-story dependency DAG; runs Kahn's algorithm with cycle detection; optionally computes a file-overlap matrix (mode=parallel) and the critical path; then renders ai\u002Fepics\u002Fepic-XXXX\u002Fepic-execution-plan.md via x-internal-write-report using the _TEMPLATE-EPIC-EXECUTION-PLAN.md template. Emits a stable JSON envelope on stdout for orchestrator consumption. Sixth skill in the x-internal-* convention and the third under internal\u002Fplan\u002F (after x-internal-load-story-context and x-internal-build-story-plan).\"\nvisibility: internal\nuser-invocable: false\nallowed-tools: Bash, Skill\nargument-hint: \"--epic-id \u003CXXXX> --mode \u003Csequential|parallel> --output \u003Cpath> [--strict-overlap]\"\ncategory: internal-plan\ncontext-budget: heavy\nrequires-capabilities: []\n---\n\n## Global Output Policy\n\n- **Language**: English ONLY.\n- **Tone**: Technical, Direct, and Concise.\n- **Efficiency**: Remove all conversational fillers and greetings to save tokens.\n\n> 🔒 **INTERNAL SKILL**\n> Esta skill é invocada apenas por outras skills (orquestradores).\n> NÃO é destinada a invocação direta pelo usuário.\n> Caller principal: `x-implement-epic` (Phase 0 \u002F 0.5 carve-out).\n> Sexta skill da convenção `x-internal-*` (após x-internal-update-status\n> pilot 0049-0005, x-internal-write-report 0049-0006,\n> x-internal-normalize-args 0049-0007, x-internal-load-story-context\n> 0049-0011, e x-internal-build-story-plan 0049-0012). Terceira skill\n> na subdir `internal\u002Fplan\u002F`. A subdir `plan\u002F` agrupa as skills que\n> orquestram lógica de planejamento (read-only computation + render);\n> difere de `internal\u002Fops\u002F`, cujas sibling skills mutam estado\n> (execution-state.json, reports).\n\n# Skill: x-internal-build-epic-plan\n\n## Purpose\n\nCarve out the Phase 0 \u002F 0.5 pre-flight of `x-implement-epic` — the\n~250 inline lines that load epic metadata, stories, and dependency\nmatrices, compute the phase ordering via Kahn's algorithm, optionally\nanalyse file overlaps, and compute the critical path — into a single\ninvocable skill with a stable JSON envelope. The orchestrator shrinks\nto a read-the-envelope consumer that then dispatches waves.\n\nResponsibilities (single):\n\n1. Load `ai\u002Fepics\u002Fepic-${epic_id}\u002Fepic-${epic_id}.md` and parse the story\n   table.\n2. Load `ai\u002Fepics\u002Fepic-${epic_id}\u002FIMPLEMENTATION-MAP.md` and extract the\n   inter-story dependency matrix.\n3. For every `story-${epic_id}-NNNN.md`, cross-validate declared\n   dependencies against the matrix and detect missing story files.\n4. Build the dependency DAG, run Kahn's algorithm, and detect cycles\n   (exit `3` with `CYCLIC_DEPENDENCY` on detection).\n5. When `--mode parallel`: compute the file-overlap matrix across\n   every pair of stories co-scheduled in the same Kahn phase.\n   Advisory by default; `--strict-overlap` escalates any hard\n   collision to a non-zero warning in the envelope (NOT a fatal\n   error — Phase 1.5 parallelism gate remains the orchestrator's\n   abort point via `x-evaluate-parallelism`).\n6. Compute the critical path (longest chain of dependencies measured\n   in story count).\n7. Render `${output}` via `x-internal-write-report` using the\n   template `_TEMPLATE-EPIC-EXECUTION-PLAN.md`.\n8. Emit a stable JSON envelope on stdout; translate every error\n   category to the exit-code catalogue below.\n\nNon-responsibilities (explicit):\n\n- The skill does NOT mutate `execution-state.json`, `**Status:**`\n  headers, or IMPLEMENTATION-MAP — those belong to\n  `x-internal-update-status` (story-0049-0005).\n- The skill does NOT run the Phase 1.5 collision gate — that is\n  `x-evaluate-parallelism`'s exclusive contract (EPIC-0041).\n- The skill does NOT dispatch story implementation waves — that is\n  `x-implement-epic`'s contract, downstream of this skill.\n- The skill does NOT re-read individual stories' planning artifacts\n  (arch\u002Fimpl\u002Ftest\u002Ftask plans) — those belong to\n  `x-internal-load-story-context` (per-story, called inside\n  `x-implement-story` Phase 0).\n- The skill does NOT write the story `**Status:**` header or trigger\n  Jira transitions — those are status-finalize concerns.\n\n## Convention Anchors (x-internal-*)\n\n| Aspect | Value | Rationale |\n| :--- | :--- | :--- |\n| Path | `internal\u002Fplan\u002Fx-internal-build-epic-plan\u002F` | `internal\u002F` prefix scopes visibility; `plan\u002F` co-locates with the sibling read-and-compute carve-outs (x-internal-load-story-context, x-internal-build-story-plan) |\n| Frontmatter `visibility` | `internal` | Generator filters these from `\u002Fhelp` menu |\n| Frontmatter `user-invocable` | `false` | Declarative complement to `visibility: internal` |\n| Body marker | `> 🔒 **INTERNAL SKILL**` block as first non-frontmatter content | Visible to humans browsing the repo; no parsing required |\n| Allowed tools | `Bash, Skill` | Minimal: `Bash` for parsing + DAG + envelope assembly, `Skill` for the single downstream `x-internal-write-report` invocation. No `Agent` — planning is deterministic computation, not subagent dispatch |\n| Naming | `x-internal-{subject}-{action}` | `epic-build-plan` = subject+action per Rule 04 skill taxonomy |\n\nAudit rule: Rule 22 (Lifecycle Integrity) validates every skill under\n`internal\u002F**` satisfies all 6 anchors above. Violations fail\n`LifecycleIntegrityAuditTest`.\n\n## Triggers\n\nBare-slash form is intentionally omitted — this skill is never\ninvoked by a human typing `\u002Fx-internal-build-epic-plan` in chat.\nAll invocations follow the Rule 13 INLINE-SKILL pattern from a\ncalling orchestrator:\n\n```markdown\nSkill(skill: \"x-internal-build-epic-plan\",\n      args: \"--epic-id XXXX --mode sequential --output ai\u002Fepics\u002Fepic-XXXX\u002Fepic-execution-plan.md\")\n```\n\n## Parameters\n\n| Parameter | Required | Default | Description |\n| :--- | :--- | :--- | :--- |\n| `--epic-id \u003Cid>` | M | — | 4-digit epic identifier (`XXXX`); zero-padded to 4 digits before use |\n| `--mode \u003Ctier>` | M | — | `sequential` or `parallel`; case-insensitive; controls whether the overlap matrix is computed |\n| `--output \u003Cpath>` | M | — | Absolute or repo-relative path where the rendered markdown is written (typically `ai\u002Fepics\u002Fepic-XXXX\u002Fepic-execution-plan.md`); must be writable |\n| `--strict-overlap` | O | `false` | When `true` in parallel mode, annotates hard collisions in the envelope with `overlapSeverity: \"hard\"`; does NOT abort the run — the caller's Phase 1.5 gate decides |\n\nAll four argument forms (`--key value`, `--key=value`, empty, and\nunknown-flag rejection) follow the Rule-14 rejection matrix: reject\nunknown flags and missing required flags with exit `64` (sysexits\n`EX_USAGE`). The `--epic-id` value is normalised to 4 digits\n(zero-padded); `--mode` is normalised to lowercase.\n\n## Response Contract\n\nOn success the skill writes a single-line JSON object to stdout:\n\n| Field | Type | Always Present | Description |\n| :--- | :--- | :--- | :--- |\n| `phases` | `Array\u003CPhase>` | yes | Ordered list of Kahn phases, each `{ \"index\": \u003Cint>, \"stories\": [\u003CstoryId>,…] }` |\n| `overlapMatrix` | `Object\u003CstoryId, Array\u003CstoryId>>` \\| `null` | no — `null` when `mode=sequential` | Map from each story to the list of co-scheduled peers touching the same files |\n| `overlapSeverity` | `String` \\| `null` | no — `null` when `mode=sequential` | One of `\"none\"` \u002F `\"soft\"` \u002F `\"regen\"` \u002F `\"hard\"`; mirrors `x-evaluate-parallelism` severity vocabulary |\n| `criticalPath` | `Array\u003CstoryId>` | yes | Longest dependency chain in the DAG (length = N stories); ties broken by lexicographic storyId |\n| `planPath` | `String` | yes | Echo of `--output` after normalisation — also the path of the rendered markdown |\n| `mode` | `String` | yes | Echo of the resolved mode (`sequential` \u002F `parallel`) |\n| `epicId` | `String` | yes | Echo of the 4-digit epic id |\n| `storyCount` | `Integer` | yes | Count of distinct stories discovered under `ai\u002Fepics\u002Fepic-${epic_id}\u002Fstory-*.md` |\n| `strictOverlap` | `Boolean` | yes | Echo of `--strict-overlap` |\n\nThe envelope shape is authoritative; callers must NOT assume field\norder. `overlapMatrix` and `overlapSeverity` are `null` (not absent)\nin sequential mode so consumers can use a single deserialisation\nschema.\n\n## Exit Codes\n\n| Code | Name | Condition | Message Format |\n| :--- | :--- | :--- | :--- |\n| 0 | SUCCESS | All steps succeeded; envelope emitted | — |\n| 1 | EPIC_NOT_FOUND | `ai\u002Fepics\u002Fepic-${epic_id}\u002F` directory does not exist | `Epic dir not found: ai\u002Fepics\u002Fepic-\u003Cid>` |\n| 2 | MAP_NOT_FOUND | `ai\u002Fepics\u002Fepic-${epic_id}\u002FIMPLEMENTATION-MAP.md` is missing | `IMPLEMENTATION-MAP.md missing under ai\u002Fepics\u002Fepic-\u003Cid>` |\n| 3 | CYCLIC_DEPENDENCY | Kahn's algorithm detected a cycle in the DAG | `Cycle detected: \u003CstoryA> -> \u003CstoryB> -> … -> \u003CstoryA>` |\n| 4 | STORY_FILE_MISSING | Dependency matrix references a story whose `.md` file is absent | `Story file missing: \u003CstoryId>.md` |\n| 5 | REPORT_WRITE_FAILED | Downstream `x-internal-write-report` returned non-zero or did not produce `${output}` | `Report write failed: \u003Cdetail>` |\n| 64 | EX_USAGE | Unknown flag, missing required flag, malformed `--epic-id` \u002F `--mode`, or unwritable `--output` | `usage: \u003Cdetail>` |\n\nNo partial-success state: the first non-recoverable error aborts the\nrun and yields a non-zero exit. The `--strict-overlap` flag does NOT\nproduce a non-zero exit; it only escalates `overlapSeverity` in the\nenvelope.\n\n## Workflow\n\n### Step 1 — Argument parsing and path resolution\n\nParse arguments with the Rule-14 single-file `while (($#))` loop;\nreject unknown flags \u002F missing required flags \u002F empty values with\nexit `64`. Normalise `--epic-id` to 4 digits (zero-padded);\nnormalise `--mode` to lowercase and verify it matches\n`^(sequential|parallel)$`. Verify `--output`'s parent directory\nexists and is writable; reject with exit `64` if not.\n\nDerive:\n\n```bash\nepic_dir=\"ai\u002Fepics\u002Fepic-${epic_id}\"\nepic_file=\"${epic_dir}\u002Fepic-${epic_id}.md\"\nmap_file=\"${epic_dir}\u002FIMPLEMENTATION-MAP.md\"\n```\n\nValidate in order:\n\n1. `[[ -d \"${epic_dir}\" ]]` — else exit `1` with `EPIC_NOT_FOUND`.\n2. `[[ -f \"${map_file}\" ]]` — else exit `2` with `MAP_NOT_FOUND`.\n3. `[[ -f \"${epic_file}\" ]]` — else exit `1` with `EPIC_NOT_FOUND`\n   (conceptually the same failure class — epic-dir without its epic\n   file is unusable; folded into code `1` for a flatter contract).\n\n### Step 2 — Load and parse artifacts\n\nParse the epic file's story table (Markdown `| storyId | …` rows)\ninto a `Set\u003CstoryId>` of DECLARED stories. Parse\n`IMPLEMENTATION-MAP.md` dependency section into a\n`Map\u003CstoryId, List\u003CstoryId>>` of EDGES (each key's list is its\n`blockedBy` set). Enumerate `ai\u002Fepics\u002Fepic-${epic_id}\u002Fstory-*.md` to\na `Set\u003CstoryId>` of ON_DISK stories.\n\nCross-validation:\n\n- For every `storyId` in EDGES.keys ∪ EDGES.values: if\n  `storyId ∉ ON_DISK`, exit `4` with `STORY_FILE_MISSING`.\n- Stories in ON_DISK but absent from EDGES are treated as zero-dep\n  roots (no error — the map is the authority for edges, but its\n  absence implies \"no declared dependency\").\n\n### Step 3 — Kahn's algorithm + cycle detection\n\nClassic Kahn: compute `inDegree` per story; seed queue with all\n`inDegree == 0` roots (sorted lexicographically for determinism);\nemit them as `phase[0].stories`; decrement neighbour in-degrees;\nstories reaching zero enter `phase[k+1]`.\n\nIf after the loop `|emitted| \u003C |stories|`, there is a cycle. Walk\nfrom any unvisited node with `inDegree > 0`, following outgoing\nedges until a node is revisited — that traversal is the minimal\ncycle chain. Emit:\n\n```\nCycle detected: \u003Cstory1> -> \u003Cstory2> -> … -> \u003Cstory1>\n```\n\nand exit `3`.\n\n### Step 4 — Overlap matrix (parallel mode only)\n\nFor `--mode parallel`, compute for every pair `(storyA, storyB)` in\nthe SAME Kahn phase:\n\n```\nfilesA = union of write+regen footprint declared in story-A's plans\nfilesB = same for story-B\noverlap = filesA ∩ filesB\n```\n\nThe footprint source is the `## File Footprint` block introduced\nby EPIC-0041 in each plan file (task \u002F story level). When the block\nis absent (legacy stories predating EPIC-0041), mark the story as\n`footprint-unknown` and include it in the matrix with an empty peer\nlist + an advisory in the envelope's `warnings` field. Never abort\n— RULE-006 (EPIC-0041) dictates \"warn, do not block\" for\nfootprint-unknown stories.\n\nClassify each non-empty overlap by the RULE-004 hotspot table:\n\n- `hard` — overlap contains any hotspot file (`SettingsAssembler.java`,\n  `HooksAssembler.java`, `CLAUDE.md`, `CHANGELOG.md`, `pom.xml`,\n  `.gitignore`, `src\u002Ftest\u002Fresources\u002Fgolden\u002F**`)\n- `regen` — overlap contains only generator-touched files\n- `soft` — overlap contains only hand-edited files outside hotspots\n- `none` — overlap is empty\n\n`overlapSeverity` at the envelope level is the MAX across all pairs\n(`hard > regen > soft > none`). `--strict-overlap` does NOT change\nthe severity function — it is already maximal; the flag is echoed so\nthe caller can decide its own threshold.\n\n### Step 5 — Critical path\n\nLongest-path in the DAG by topological order. For every story,\n`longest[story] = max(longest[dep]) + 1` iterating in Kahn order.\nThe critical path is the chain ending at the story with maximum\n`longest[story]`, unwound via back-pointers. Ties broken by\nlexicographic storyId.\n\n### Step 6 — Render markdown via x-internal-write-report\n\nInvoke the downstream via the Rule 13 INLINE-SKILL pattern:\n\n```markdown\nSkill(skill: \"x-internal-write-report\",\n      args: \"--template _TEMPLATE-EPIC-EXECUTION-PLAN.md --output ${output} --data-stdin\")\n```\n\nPipe the JSON envelope (augmented with a `renderedAt` ISO-8601\ntimestamp) to the child's stdin. The child is responsible for\nplaceholder substitution; this skill passes the data as-is.\n\nOn non-zero exit or absent `${output}`, emit:\n`Report write failed: \u003Cchild stderr line>` and exit `5`.\n\n### Step 7 — Emit the envelope\n\nAssemble via `jq -nc`:\n\n```bash\njq -nc \\\n  --arg epicId   \"${epic_id}\" \\\n  --arg mode     \"${mode}\" \\\n  --arg planPath \"${output}\" \\\n  --argjson phases        \"${phases_json}\" \\\n  --argjson overlapMatrix \"${overlap_json_or_null}\" \\\n  --arg     overlapSeverity \"${severity_or_null}\" \\\n  --argjson criticalPath  \"${critical_json}\" \\\n  --argjson storyCount    \"${story_count}\" \\\n  --argjson strictOverlap \"${strict_bool}\" \\\n  '{ epicId:$epicId, mode:$mode, phases:$phases,\n     overlapMatrix: (if $overlapMatrix == null then null\n                     else $overlapMatrix end),\n     overlapSeverity: (if $overlapSeverity == \"\" then null\n                       else $overlapSeverity end),\n     criticalPath:$criticalPath, planPath:$planPath,\n     storyCount:$storyCount, strictOverlap:$strictOverlap }'\n```\n\nEmit on stdout as a single line terminated by `\\n`. Exit `0`.\n\n## Examples\n\n### Example 1 — Happy path: sequential mode\n\n```bash\nSkill(skill: \"x-internal-build-epic-plan\",\n      args: \"--epic-id XXXX --mode sequential --output ai\u002Fepics\u002Fepic-XXXX\u002Fepic-execution-plan.md\")\n```\n\nOutput:\n```json\n{\"epicId\":\"XXXX\",\"mode\":\"sequential\",\"phases\":[{\"index\":0,\"stories\":[\"story-XXXX-0001\",\"story-XXXX-0002\",\"story-XXXX-0003\",\"story-XXXX-0004\"]},{\"index\":1,\"stories\":[\"story-XXXX-0005\",\"story-XXXX-0006\",\"story-XXXX-0007\",\"story-XXXX-0008\"]},{\"index\":2,\"stories\":[\"story-XXXX-0009\",\"story-XXXX-0010\",\"story-XXXX-0011\",\"story-XXXX-0012\",\"story-XXXX-0013\",\"story-XXXX-0014\",\"story-XXXX-0015\",\"story-XXXX-0016\",\"story-XXXX-0017\"]},{\"index\":3,\"stories\":[\"story-XXXX-0018\",\"story-XXXX-0019\"]},{\"index\":4,\"stories\":[\"story-XXXX-0020\",\"story-XXXX-0021\",\"story-XXXX-0022\"]}],\"overlapMatrix\":null,\"overlapSeverity\":null,\"criticalPath\":[\"story-XXXX-0001\",\"story-XXXX-0005\",\"story-XXXX-0018\",\"story-XXXX-0020\"],\"planPath\":\"ai\u002Fepics\u002Fepic-XXXX\u002Fepic-execution-plan.md\",\"storyCount\":22,\"strictOverlap\":false}\n```\nExit: 0.\n\n### Example 2 — Parallel mode with overlap\n\n```bash\nSkill(skill: \"x-internal-build-epic-plan\",\n      args: \"--epic-id XXXX --mode parallel --output ai\u002Fepics\u002Fepic-XXXX\u002Fepic-execution-plan.md\")\n```\n\nOutput (truncated):\n```json\n{\"epicId\":\"0049\",\"mode\":\"parallel\",\"phases\":[…],\"overlapMatrix\":{\"story-0049-0006\":[\"story-0049-0007\"],\"story-0049-0007\":[\"story-0049-0006\"]},\"overlapSeverity\":\"regen\",\"criticalPath\":[…],\"planPath\":\"…\",\"storyCount\":22,\"strictOverlap\":false}\n```\nExit: 0.\n\n### Example 3 — Cyclic dependency\n\nSynthetic epic where `story-A` blockedBy `story-B` and\n`story-B` blockedBy `story-A`.\n\nStderr:\n```\nCycle detected: story-0099-0001 -> story-0099-0002 -> story-0099-0001\n```\nExit: 3.\n\n### Example 4 — Epic directory missing\n\n```bash\nSkill(skill: \"x-internal-build-epic-plan\",\n      args: \"--epic-id 9999 --mode sequential --output \u002Ftmp\u002Fout.md\")\n```\n\nStderr:\n```\nEpic dir not found: ai\u002Fepics\u002Fepic-XXXX\n```\nExit: 1.\n\n### Example 5 — Story file missing\n\nThe IMPLEMENTATION-MAP references `story-0049-0099` but no\n`story-0049-0099.md` exists on disk.\n\nStderr:\n```\nStory file missing: story-0049-0099.md\n```\nExit: 4.\n\n### Example 6 — Boundary: epic with 1 story, zero deps\n\n```bash\nSkill(skill: \"x-internal-build-epic-plan\",\n      args: \"--epic-id YYYY --mode sequential --output ai\u002Fepics\u002Fepic-YYYY\u002Fepic-execution-plan.md\")\n```\n\nOutput:\n```json\n{\"epicId\":\"YYYY\",\"mode\":\"sequential\",\"phases\":[{\"index\":0,\"stories\":[\"story-YYYY-0001\"]}],\"overlapMatrix\":null,\"overlapSeverity\":null,\"criticalPath\":[\"story-YYYY-0001\"],\"planPath\":\"ai\u002Fepics\u002Fepic-YYYY\u002Fepic-execution-plan.md\",\"storyCount\":1,\"strictOverlap\":false}\n```\nExit: 0.\n\n## Outputs\n\n| Artifact | Path | Description |\n| :--- | :--- | :--- |\n| Response envelope | stdout | Single-line JSON matching the Response Contract |\n| Error diagnostic | stderr | Single line, non-empty only on exit ≠ 0 |\n| Execution plan markdown | `${output}` (typically `ai\u002Fepics\u002Fepic-XXXX\u002Fepic-execution-plan.md`) | Rendered by `x-internal-write-report` using the `_TEMPLATE-EPIC-EXECUTION-PLAN.md` template |\n\nThe skill DOES create files — specifically the `${output}` markdown —\nbut only via the `x-internal-write-report` delegation. The\n`allowed-tools` frontmatter therefore does not include `Write`: the\nwrite happens inside the child skill's own adapter, not directly\nfrom this skill's body.\n\n## Error Handling\n\n| Scenario | Action |\n| :--- | :--- |\n| Missing required flag | Print `usage:` banner to stderr; exit 64 |\n| Unknown flag | Print `usage: unknown flag …` to stderr; exit 64 |\n| Malformed `--epic-id` | `usage: --epic-id must be a 4-digit integer`; exit 64 |\n| `--mode` unrecognised | `usage: --mode must be sequential \u002F parallel`; exit 64 |\n| `--output` path unwritable | `usage: --output path not writable`; exit 64 |\n| Missing epic dir | `Epic dir not found: ai\u002Fepics\u002Fepic-\u003Cid>`; exit 1 |\n| Missing epic file | `Epic file not found: ai\u002Fepics\u002Fepic-\u003Cid>\u002Fepic-\u003Cid>.md`; exit 1 |\n| Missing IMPLEMENTATION-MAP | `IMPLEMENTATION-MAP.md missing under ai\u002Fepics\u002Fepic-\u003Cid>`; exit 2 |\n| Cycle detected in DAG | `Cycle detected: \u003Cchain>`; exit 3 |\n| Story-file referenced by map but absent | `Story file missing: \u003CstoryId>.md`; exit 4 |\n| `x-internal-write-report` non-zero | `Report write failed: \u003Cchild stderr line>`; exit 5 |\n| `x-internal-write-report` success but `${output}` absent | `Report write failed: expected output not produced`; exit 5 |\n| `jq` absent on PATH | Exit 127 with `jq is required`; abort before any file read |\n| Story has no `## File Footprint` block (parallel mode) | Emit advisory in envelope `warnings`; include story in matrix with empty peer list; do NOT abort |\n\nThe skill is fail-fast on structural errors (exit 1–4); reporting\nfailures (exit 5) preserve the computed envelope on stderr so the\ncaller can choose to retry just the render step. The `warnings`\nadvisory for footprint-unknown stories is non-fatal by design\n(EPIC-0041 RULE-006).\n\n## Performance Contract\n\nTarget: plan computation strictly under 5 seconds for epics up to\n30 stories on a typical developer machine — this is the Global DoD\nthreshold from story-0049-0009 §4. The dominant cost is the\nfile-system scan of `story-*.md` + footprint-block parsing; DAG\nprocessing is O(V + E) and negligible.\n\nThe render step (`x-internal-write-report`) is measured separately\nand is typically 0.5–2 seconds for a 22-story epic; it is NOT\ncounted against the 5-second DoD because the DoD bounds plan\ncomputation, not the physical write.\n\n## Testing\n\nAcceptance scenarios (mirroring Section 7 of story-0049-0009):\n\n1. **Happy path — sequential.** Epic-0049 with 22 stories; 5 phases\n   emitted; critical path length ≥ 4; markdown produced at\n   `--output`.\n2. **Boundary — single story.** Epic with only\n   `story-XXXX-0001`; 1 phase with 1 story; critical path length 1.\n3. **Error — cyclic dependency.** Synthetic epic A→B, B→A; exit 3;\n   stderr contains `CYCLIC_DEPENDENCY`.\n4. **Error — epic dir missing.** `--epic-id 9999`; exit 1.\n5. **Error — map missing.** Epic dir exists without\n   `IMPLEMENTATION-MAP.md`; exit 2.\n6. **Error — story file missing.** Map references\n   `story-XXXX-0099.md` but file absent; exit 4.\n7. **Parallel — overlap computed.** Two stories in the same phase\n   touching the same file; `overlapMatrix` populated;\n   `overlapSeverity` matches RULE-004 classification.\n\nCoverage requirement: ≥ 95% line \u002F ≥ 90% branch across the\nparser, DAG, overlap matrix, and envelope-assembly logic. Goldens\n(if added) lock the SKILL.md rendering under\n`src\u002Ftest\u002Fresources\u002Fgolden\u002Finternal\u002Fplan\u002Fx-internal-build-epic-plan\u002F`\nper the sibling pattern (story-0049-0012, story-0049-0014).\n\n## Generator Filter Contract\n\nThe `ia-dev-env` generator MUST exclude skills with\n`visibility: internal` from:\n\n1. The `.claude\u002FREADME.md` skill-inventory table.\n2. The `\u002Fhelp` menu listing surfaced by Claude Code.\n3. User-facing autocomplete in the chat input.\n\nInternal skills are still copied into `.claude\u002Fskills\u002F` (flat\nlayout) so `Skill(skill: \"x-internal-…\")` invocations from other\nskills resolve correctly. The invariant: **user cannot see them;\norchestrators can invoke them.**\n\n## Telemetry\n\nInternal skills DO NOT emit `phase.start` \u002F `phase.end` markers —\ntelemetry is produced by the invoking orchestrator (the `phase`\nwrapping the orchestrator's own step is the correct aggregation\nboundary). Passive hooks still capture `tool.call` for each\nunderlying `Skill` \u002F `Bash` invocation made from inside the skill\nbody.\n\nReference: Rule 13 (Skill Invocation Protocol), Rule 22 (Lifecycle\nIntegrity Audit), ADR-0010 (Interactive Gates Convention — exempts\ninternal skills from the 3-option menu contract), ADR-0006\n(File-Conflict-Aware Parallelism — defines RULE-004 hotspot table\nand RULE-006 footprint-unknown advisory).\n\n## Integration Notes\n\n| Skill | Relationship | Context |\n| :--- | :--- | :--- |\n| `x-implement-epic` | caller (primary) | Phase 0 \u002F 0.5 carve-out: ~250 inline lines collapse to one `Skill(skill: \"x-internal-build-epic-plan\", …)` invocation in story-0049-0018 |\n| `x-internal-write-report` | delegate (Step 6) | Renders `epic-execution-plan.md` using `_TEMPLATE-EPIC-EXECUTION-PLAN.md`; defined in story-0049-0006 (MERGED) |\n| `x-evaluate-parallelism` | downstream peer | Phase 1.5 of the caller consumes the `overlapMatrix` to compute per-wave collision classification (EPIC-0041) |\n| `x-internal-update-status` | peer | Separate concern (mutates state); never invoked from this skill |\n| `x-internal-load-story-context` | peer | Sibling read-only carve-out at the story level; never invoked from this skill |\n| `x-internal-build-story-plan` | peer | Sibling story-level planning carve-out; never invoked from this skill |\n\nDownstream stories that depend on this carve-out:\nstory-0049-0018 (`x-implement-epic` refactor consumes the envelope\nand deletes the inline Phase 0 \u002F 0.5 blocks).\n\nFull workflow detail (parser grammar for the IMPLEMENTATION-MAP\ndependency table, Kahn-algorithm pseudocode, footprint-block regex,\noverlap-severity decision table, and the `x-internal-write-report`\nstdin schema) lives in\n[`references\u002Ffull-protocol.md`](references\u002Ffull-protocol.md)\nper ADR-0011.\n","## Global Output Policy\n\n- **Language**: English ONLY.\n- **Tone**: Technical, Direct, and Concise.\n- **Efficiency**: Remove all conversational fillers and greetings to save tokens.\n\n> 🔒 **INTERNAL SKILL**\n> Esta skill é invocada apenas por outras skills (orquestradores).\n> NÃO é destinada a invocação direta pelo usuário.\n> Caller principal: `x-implement-epic` (Phase 0 \u002F 0.5 carve-out).\n> Sexta skill da convenção `x-internal-*` (após x-internal-update-status\n> pilot 0049-0005, x-internal-write-report 0049-0006,\n> x-internal-normalize-args 0049-0007, x-internal-load-story-context\n> 0049-0011, e x-internal-build-story-plan 0049-0012). Terceira skill\n> na subdir `internal\u002Fplan\u002F`. A subdir `plan\u002F` agrupa as skills que\n> orquestram lógica de planejamento (read-only computation + render);\n> difere de `internal\u002Fops\u002F`, cujas sibling skills mutam estado\n> (execution-state.json, reports).\n\n# Skill: x-internal-build-epic-plan\n\n## Purpose\n\nCarve out the Phase 0 \u002F 0.5 pre-flight of `x-implement-epic` — the\n~250 inline lines that load epic metadata, stories, and dependency\nmatrices, compute the phase ordering via Kahn's algorithm, optionally\nanalyse file overlaps, and compute the critical path — into a single\ninvocable skill with a stable JSON envelope. The orchestrator shrinks\nto a read-the-envelope consumer that then dispatches waves.\n\nResponsibilities (single):\n\n1. Load `ai\u002Fepics\u002Fepic-${epic_id}\u002Fepic-${epic_id}.md` and parse the story\n   table.\n2. Load `ai\u002Fepics\u002Fepic-${epic_id}\u002FIMPLEMENTATION-MAP.md` and extract the\n   inter-story dependency matrix.\n3. For every `story-${epic_id}-NNNN.md`, cross-validate declared\n   dependencies against the matrix and detect missing story files.\n4. Build the dependency DAG, run Kahn's algorithm, and detect cycles\n   (exit `3` with `CYCLIC_DEPENDENCY` on detection).\n5. When `--mode parallel`: compute the file-overlap matrix across\n   every pair of stories co-scheduled in the same Kahn phase.\n   Advisory by default; `--strict-overlap` escalates any hard\n   collision to a non-zero warning in the envelope (NOT a fatal\n   error — Phase 1.5 parallelism gate remains the orchestrator's\n   abort point via `x-evaluate-parallelism`).\n6. Compute the critical path (longest chain of dependencies measured\n   in story count).\n7. Render `${output}` via `x-internal-write-report` using the\n   template `_TEMPLATE-EPIC-EXECUTION-PLAN.md`.\n8. Emit a stable JSON envelope on stdout; translate every error\n   category to the exit-code catalogue below.\n\nNon-responsibilities (explicit):\n\n- The skill does NOT mutate `execution-state.json`, `**Status:**`\n  headers, or IMPLEMENTATION-MAP — those belong to\n  `x-internal-update-status` (story-0049-0005).\n- The skill does NOT run the Phase 1.5 collision gate — that is\n  `x-evaluate-parallelism`'s exclusive contract (EPIC-0041).\n- The skill does NOT dispatch story implementation waves — that is\n  `x-implement-epic`'s contract, downstream of this skill.\n- The skill does NOT re-read individual stories' planning artifacts\n  (arch\u002Fimpl\u002Ftest\u002Ftask plans) — those belong to\n  `x-internal-load-story-context` (per-story, called inside\n  `x-implement-story` Phase 0).\n- The skill does NOT write the story `**Status:**` header or trigger\n  Jira transitions — those are status-finalize concerns.\n\n## Convention Anchors (x-internal-*)\n\n| Aspect | Value | Rationale |\n| :--- | :--- | :--- |\n| Path | `internal\u002Fplan\u002Fx-internal-build-epic-plan\u002F` | `internal\u002F` prefix scopes visibility; `plan\u002F` co-locates with the sibling read-and-compute carve-outs (x-internal-load-story-context, x-internal-build-story-plan) |\n| Frontmatter `visibility` | `internal` | Generator filters these from `\u002Fhelp` menu |\n| Frontmatter `user-invocable` | `false` | Declarative complement to `visibility: internal` |\n| Body marker | `> 🔒 **INTERNAL SKILL**` block as first non-frontmatter content | Visible to humans browsing the repo; no parsing required |\n| Allowed tools | `Bash, Skill` | Minimal: `Bash` for parsing + DAG + envelope assembly, `Skill` for the single downstream `x-internal-write-report` invocation. No `Agent` — planning is deterministic computation, not subagent dispatch |\n| Naming | `x-internal-{subject}-{action}` | `epic-build-plan` = subject+action per Rule 04 skill taxonomy |\n\nAudit rule: Rule 22 (Lifecycle Integrity) validates every skill under\n`internal\u002F**` satisfies all 6 anchors above. Violations fail\n`LifecycleIntegrityAuditTest`.\n\n## Triggers\n\nBare-slash form is intentionally omitted — this skill is never\ninvoked by a human typing `\u002Fx-internal-build-epic-plan` in chat.\nAll invocations follow the Rule 13 INLINE-SKILL pattern from a\ncalling orchestrator:\n\n```markdown\nSkill(skill: \"x-internal-build-epic-plan\",\n      args: \"--epic-id XXXX --mode sequential --output ai\u002Fepics\u002Fepic-XXXX\u002Fepic-execution-plan.md\")\n```\n\n## Parameters\n\n| Parameter | Required | Default | Description |\n| :--- | :--- | :--- | :--- |\n| `--epic-id \u003Cid>` | M | — | 4-digit epic identifier (`XXXX`); zero-padded to 4 digits before use |\n| `--mode \u003Ctier>` | M | — | `sequential` or `parallel`; case-insensitive; controls whether the overlap matrix is computed |\n| `--output \u003Cpath>` | M | — | Absolute or repo-relative path where the rendered markdown is written (typically `ai\u002Fepics\u002Fepic-XXXX\u002Fepic-execution-plan.md`); must be writable |\n| `--strict-overlap` | O | `false` | When `true` in parallel mode, annotates hard collisions in the envelope with `overlapSeverity: \"hard\"`; does NOT abort the run — the caller's Phase 1.5 gate decides |\n\nAll four argument forms (`--key value`, `--key=value`, empty, and\nunknown-flag rejection) follow the Rule-14 rejection matrix: reject\nunknown flags and missing required flags with exit `64` (sysexits\n`EX_USAGE`). The `--epic-id` value is normalised to 4 digits\n(zero-padded); `--mode` is normalised to lowercase.\n\n## Response Contract\n\nOn success the skill writes a single-line JSON object to stdout:\n\n| Field | Type | Always Present | Description |\n| :--- | :--- | :--- | :--- |\n| `phases` | `Array\u003CPhase>` | yes | Ordered list of Kahn phases, each `{ \"index\": \u003Cint>, \"stories\": [\u003CstoryId>,…] }` |\n| `overlapMatrix` | `Object\u003CstoryId, Array\u003CstoryId>>` \\| `null` | no — `null` when `mode=sequential` | Map from each story to the list of co-scheduled peers touching the same files |\n| `overlapSeverity` | `String` \\| `null` | no — `null` when `mode=sequential` | One of `\"none\"` \u002F `\"soft\"` \u002F `\"regen\"` \u002F `\"hard\"`; mirrors `x-evaluate-parallelism` severity vocabulary |\n| `criticalPath` | `Array\u003CstoryId>` | yes | Longest dependency chain in the DAG (length = N stories); ties broken by lexicographic storyId |\n| `planPath` | `String` | yes | Echo of `--output` after normalisation — also the path of the rendered markdown |\n| `mode` | `String` | yes | Echo of the resolved mode (`sequential` \u002F `parallel`) |\n| `epicId` | `String` | yes | Echo of the 4-digit epic id |\n| `storyCount` | `Integer` | yes | Count of distinct stories discovered under `ai\u002Fepics\u002Fepic-${epic_id}\u002Fstory-*.md` |\n| `strictOverlap` | `Boolean` | yes | Echo of `--strict-overlap` |\n\nThe envelope shape is authoritative; callers must NOT assume field\norder. `overlapMatrix` and `overlapSeverity` are `null` (not absent)\nin sequential mode so consumers can use a single deserialisation\nschema.\n\n## Exit Codes\n\n| Code | Name | Condition | Message Format |\n| :--- | :--- | :--- | :--- |\n| 0 | SUCCESS | All steps succeeded; envelope emitted | — |\n| 1 | EPIC_NOT_FOUND | `ai\u002Fepics\u002Fepic-${epic_id}\u002F` directory does not exist | `Epic dir not found: ai\u002Fepics\u002Fepic-\u003Cid>` |\n| 2 | MAP_NOT_FOUND | `ai\u002Fepics\u002Fepic-${epic_id}\u002FIMPLEMENTATION-MAP.md` is missing | `IMPLEMENTATION-MAP.md missing under ai\u002Fepics\u002Fepic-\u003Cid>` |\n| 3 | CYCLIC_DEPENDENCY | Kahn's algorithm detected a cycle in the DAG | `Cycle detected: \u003CstoryA> -> \u003CstoryB> -> … -> \u003CstoryA>` |\n| 4 | STORY_FILE_MISSING | Dependency matrix references a story whose `.md` file is absent | `Story file missing: \u003CstoryId>.md` |\n| 5 | REPORT_WRITE_FAILED | Downstream `x-internal-write-report` returned non-zero or did not produce `${output}` | `Report write failed: \u003Cdetail>` |\n| 64 | EX_USAGE | Unknown flag, missing required flag, malformed `--epic-id` \u002F `--mode`, or unwritable `--output` | `usage: \u003Cdetail>` |\n\nNo partial-success state: the first non-recoverable error aborts the\nrun and yields a non-zero exit. The `--strict-overlap` flag does NOT\nproduce a non-zero exit; it only escalates `overlapSeverity` in the\nenvelope.\n\n## Workflow\n\n### Step 1 — Argument parsing and path resolution\n\nParse arguments with the Rule-14 single-file `while (($#))` loop;\nreject unknown flags \u002F missing required flags \u002F empty values with\nexit `64`. Normalise `--epic-id` to 4 digits (zero-padded);\nnormalise `--mode` to lowercase and verify it matches\n`^(sequential|parallel)$`. Verify `--output`'s parent directory\nexists and is writable; reject with exit `64` if not.\n\nDerive:\n\n```bash\nepic_dir=\"ai\u002Fepics\u002Fepic-${epic_id}\"\nepic_file=\"${epic_dir}\u002Fepic-${epic_id}.md\"\nmap_file=\"${epic_dir}\u002FIMPLEMENTATION-MAP.md\"\n```\n\nValidate in order:\n\n1. `[[ -d \"${epic_dir}\" ]]` — else exit `1` with `EPIC_NOT_FOUND`.\n2. `[[ -f \"${map_file}\" ]]` — else exit `2` with `MAP_NOT_FOUND`.\n3. `[[ -f \"${epic_file}\" ]]` — else exit `1` with `EPIC_NOT_FOUND`\n   (conceptually the same failure class — epic-dir without its epic\n   file is unusable; folded into code `1` for a flatter contract).\n\n### Step 2 — Load and parse artifacts\n\nParse the epic file's story table (Markdown `| storyId | …` rows)\ninto a `Set\u003CstoryId>` of DECLARED stories. Parse\n`IMPLEMENTATION-MAP.md` dependency section into a\n`Map\u003CstoryId, List\u003CstoryId>>` of EDGES (each key's list is its\n`blockedBy` set). Enumerate `ai\u002Fepics\u002Fepic-${epic_id}\u002Fstory-*.md` to\na `Set\u003CstoryId>` of ON_DISK stories.\n\nCross-validation:\n\n- For every `storyId` in EDGES.keys ∪ EDGES.values: if\n  `storyId ∉ ON_DISK`, exit `4` with `STORY_FILE_MISSING`.\n- Stories in ON_DISK but absent from EDGES are treated as zero-dep\n  roots (no error — the map is the authority for edges, but its\n  absence implies \"no declared dependency\").\n\n### Step 3 — Kahn's algorithm + cycle detection\n\nClassic Kahn: compute `inDegree` per story; seed queue with all\n`inDegree == 0` roots (sorted lexicographically for determinism);\nemit them as `phase[0].stories`; decrement neighbour in-degrees;\nstories reaching zero enter `phase[k+1]`.\n\nIf after the loop `|emitted| \u003C |stories|`, there is a cycle. Walk\nfrom any unvisited node with `inDegree > 0`, following outgoing\nedges until a node is revisited — that traversal is the minimal\ncycle chain. Emit:\n\n```\nCycle detected: \u003Cstory1> -> \u003Cstory2> -> … -> \u003Cstory1>\n```\n\nand exit `3`.\n\n### Step 4 — Overlap matrix (parallel mode only)\n\nFor `--mode parallel`, compute for every pair `(storyA, storyB)` in\nthe SAME Kahn phase:\n\n```\nfilesA = union of write+regen footprint declared in story-A's plans\nfilesB = same for story-B\noverlap = filesA ∩ filesB\n```\n\nThe footprint source is the `## File Footprint` block introduced\nby EPIC-0041 in each plan file (task \u002F story level). When the block\nis absent (legacy stories predating EPIC-0041), mark the story as\n`footprint-unknown` and include it in the matrix with an empty peer\nlist + an advisory in the envelope's `warnings` field. Never abort\n— RULE-006 (EPIC-0041) dictates \"warn, do not block\" for\nfootprint-unknown stories.\n\nClassify each non-empty overlap by the RULE-004 hotspot table:\n\n- `hard` — overlap contains any hotspot file (`SettingsAssembler.java`,\n  `HooksAssembler.java`, `CLAUDE.md`, `CHANGELOG.md`, `pom.xml`,\n  `.gitignore`, `src\u002Ftest\u002Fresources\u002Fgolden\u002F**`)\n- `regen` — overlap contains only generator-touched files\n- `soft` — overlap contains only hand-edited files outside hotspots\n- `none` — overlap is empty\n\n`overlapSeverity` at the envelope level is the MAX across all pairs\n(`hard > regen > soft > none`). `--strict-overlap` does NOT change\nthe severity function — it is already maximal; the flag is echoed so\nthe caller can decide its own threshold.\n\n### Step 5 — Critical path\n\nLongest-path in the DAG by topological order. For every story,\n`longest[story] = max(longest[dep]) + 1` iterating in Kahn order.\nThe critical path is the chain ending at the story with maximum\n`longest[story]`, unwound via back-pointers. Ties broken by\nlexicographic storyId.\n\n### Step 6 — Render markdown via x-internal-write-report\n\nInvoke the downstream via the Rule 13 INLINE-SKILL pattern:\n\n```markdown\nSkill(skill: \"x-internal-write-report\",\n      args: \"--template _TEMPLATE-EPIC-EXECUTION-PLAN.md --output ${output} --data-stdin\")\n```\n\nPipe the JSON envelope (augmented with a `renderedAt` ISO-8601\ntimestamp) to the child's stdin. The child is responsible for\nplaceholder substitution; this skill passes the data as-is.\n\nOn non-zero exit or absent `${output}`, emit:\n`Report write failed: \u003Cchild stderr line>` and exit `5`.\n\n### Step 7 — Emit the envelope\n\nAssemble via `jq -nc`:\n\n```bash\njq -nc \\\n  --arg epicId   \"${epic_id}\" \\\n  --arg mode     \"${mode}\" \\\n  --arg planPath \"${output}\" \\\n  --argjson phases        \"${phases_json}\" \\\n  --argjson overlapMatrix \"${overlap_json_or_null}\" \\\n  --arg     overlapSeverity \"${severity_or_null}\" \\\n  --argjson criticalPath  \"${critical_json}\" \\\n  --argjson storyCount    \"${story_count}\" \\\n  --argjson strictOverlap \"${strict_bool}\" \\\n  '{ epicId:$epicId, mode:$mode, phases:$phases,\n     overlapMatrix: (if $overlapMatrix == null then null\n                     else $overlapMatrix end),\n     overlapSeverity: (if $overlapSeverity == \"\" then null\n                       else $overlapSeverity end),\n     criticalPath:$criticalPath, planPath:$planPath,\n     storyCount:$storyCount, strictOverlap:$strictOverlap }'\n```\n\nEmit on stdout as a single line terminated by `\\n`. Exit `0`.\n\n## Examples\n\n### Example 1 — Happy path: sequential mode\n\n```bash\nSkill(skill: \"x-internal-build-epic-plan\",\n      args: \"--epic-id XXXX --mode sequential --output ai\u002Fepics\u002Fepic-XXXX\u002Fepic-execution-plan.md\")\n```\n\nOutput:\n```json\n{\"epicId\":\"XXXX\",\"mode\":\"sequential\",\"phases\":[{\"index\":0,\"stories\":[\"story-XXXX-0001\",\"story-XXXX-0002\",\"story-XXXX-0003\",\"story-XXXX-0004\"]},{\"index\":1,\"stories\":[\"story-XXXX-0005\",\"story-XXXX-0006\",\"story-XXXX-0007\",\"story-XXXX-0008\"]},{\"index\":2,\"stories\":[\"story-XXXX-0009\",\"story-XXXX-0010\",\"story-XXXX-0011\",\"story-XXXX-0012\",\"story-XXXX-0013\",\"story-XXXX-0014\",\"story-XXXX-0015\",\"story-XXXX-0016\",\"story-XXXX-0017\"]},{\"index\":3,\"stories\":[\"story-XXXX-0018\",\"story-XXXX-0019\"]},{\"index\":4,\"stories\":[\"story-XXXX-0020\",\"story-XXXX-0021\",\"story-XXXX-0022\"]}],\"overlapMatrix\":null,\"overlapSeverity\":null,\"criticalPath\":[\"story-XXXX-0001\",\"story-XXXX-0005\",\"story-XXXX-0018\",\"story-XXXX-0020\"],\"planPath\":\"ai\u002Fepics\u002Fepic-XXXX\u002Fepic-execution-plan.md\",\"storyCount\":22,\"strictOverlap\":false}\n```\nExit: 0.\n\n### Example 2 — Parallel mode with overlap\n\n```bash\nSkill(skill: \"x-internal-build-epic-plan\",\n      args: \"--epic-id XXXX --mode parallel --output ai\u002Fepics\u002Fepic-XXXX\u002Fepic-execution-plan.md\")\n```\n\nOutput (truncated):\n```json\n{\"epicId\":\"0049\",\"mode\":\"parallel\",\"phases\":[…],\"overlapMatrix\":{\"story-0049-0006\":[\"story-0049-0007\"],\"story-0049-0007\":[\"story-0049-0006\"]},\"overlapSeverity\":\"regen\",\"criticalPath\":[…],\"planPath\":\"…\",\"storyCount\":22,\"strictOverlap\":false}\n```\nExit: 0.\n\n### Example 3 — Cyclic dependency\n\nSynthetic epic where `story-A` blockedBy `story-B` and\n`story-B` blockedBy `story-A`.\n\nStderr:\n```\nCycle detected: story-0099-0001 -> story-0099-0002 -> story-0099-0001\n```\nExit: 3.\n\n### Example 4 — Epic directory missing\n\n```bash\nSkill(skill: \"x-internal-build-epic-plan\",\n      args: \"--epic-id 9999 --mode sequential --output \u002Ftmp\u002Fout.md\")\n```\n\nStderr:\n```\nEpic dir not found: ai\u002Fepics\u002Fepic-XXXX\n```\nExit: 1.\n\n### Example 5 — Story file missing\n\nThe IMPLEMENTATION-MAP references `story-0049-0099` but no\n`story-0049-0099.md` exists on disk.\n\nStderr:\n```\nStory file missing: story-0049-0099.md\n```\nExit: 4.\n\n### Example 6 — Boundary: epic with 1 story, zero deps\n\n```bash\nSkill(skill: \"x-internal-build-epic-plan\",\n      args: \"--epic-id YYYY --mode sequential --output ai\u002Fepics\u002Fepic-YYYY\u002Fepic-execution-plan.md\")\n```\n\nOutput:\n```json\n{\"epicId\":\"YYYY\",\"mode\":\"sequential\",\"phases\":[{\"index\":0,\"stories\":[\"story-YYYY-0001\"]}],\"overlapMatrix\":null,\"overlapSeverity\":null,\"criticalPath\":[\"story-YYYY-0001\"],\"planPath\":\"ai\u002Fepics\u002Fepic-YYYY\u002Fepic-execution-plan.md\",\"storyCount\":1,\"strictOverlap\":false}\n```\nExit: 0.\n\n## Outputs\n\n| Artifact | Path | Description |\n| :--- | :--- | :--- |\n| Response envelope | stdout | Single-line JSON matching the Response Contract |\n| Error diagnostic | stderr | Single line, non-empty only on exit ≠ 0 |\n| Execution plan markdown | `${output}` (typically `ai\u002Fepics\u002Fepic-XXXX\u002Fepic-execution-plan.md`) | Rendered by `x-internal-write-report` using the `_TEMPLATE-EPIC-EXECUTION-PLAN.md` template |\n\nThe skill DOES create files — specifically the `${output}` markdown —\nbut only via the `x-internal-write-report` delegation. The\n`allowed-tools` frontmatter therefore does not include `Write`: the\nwrite happens inside the child skill's own adapter, not directly\nfrom this skill's body.\n\n## Error Handling\n\n| Scenario | Action |\n| :--- | :--- |\n| Missing required flag | Print `usage:` banner to stderr; exit 64 |\n| Unknown flag | Print `usage: unknown flag …` to stderr; exit 64 |\n| Malformed `--epic-id` | `usage: --epic-id must be a 4-digit integer`; exit 64 |\n| `--mode` unrecognised | `usage: --mode must be sequential \u002F parallel`; exit 64 |\n| `--output` path unwritable | `usage: --output path not writable`; exit 64 |\n| Missing epic dir | `Epic dir not found: ai\u002Fepics\u002Fepic-\u003Cid>`; exit 1 |\n| Missing epic file | `Epic file not found: ai\u002Fepics\u002Fepic-\u003Cid>\u002Fepic-\u003Cid>.md`; exit 1 |\n| Missing IMPLEMENTATION-MAP | `IMPLEMENTATION-MAP.md missing under ai\u002Fepics\u002Fepic-\u003Cid>`; exit 2 |\n| Cycle detected in DAG | `Cycle detected: \u003Cchain>`; exit 3 |\n| Story-file referenced by map but absent | `Story file missing: \u003CstoryId>.md`; exit 4 |\n| `x-internal-write-report` non-zero | `Report write failed: \u003Cchild stderr line>`; exit 5 |\n| `x-internal-write-report` success but `${output}` absent | `Report write failed: expected output not produced`; exit 5 |\n| `jq` absent on PATH | Exit 127 with `jq is required`; abort before any file read |\n| Story has no `## File Footprint` block (parallel mode) | Emit advisory in envelope `warnings`; include story in matrix with empty peer list; do NOT abort |\n\nThe skill is fail-fast on structural errors (exit 1–4); reporting\nfailures (exit 5) preserve the computed envelope on stderr so the\ncaller can choose to retry just the render step. The `warnings`\nadvisory for footprint-unknown stories is non-fatal by design\n(EPIC-0041 RULE-006).\n\n## Performance Contract\n\nTarget: plan computation strictly under 5 seconds for epics up to\n30 stories on a typical developer machine — this is the Global DoD\nthreshold from story-0049-0009 §4. The dominant cost is the\nfile-system scan of `story-*.md` + footprint-block parsing; DAG\nprocessing is O(V + E) and negligible.\n\nThe render step (`x-internal-write-report`) is measured separately\nand is typically 0.5–2 seconds for a 22-story epic; it is NOT\ncounted against the 5-second DoD because the DoD bounds plan\ncomputation, not the physical write.\n\n## Testing\n\nAcceptance scenarios (mirroring Section 7 of story-0049-0009):\n\n1. **Happy path — sequential.** Epic-0049 with 22 stories; 5 phases\n   emitted; critical path length ≥ 4; markdown produced at\n   `--output`.\n2. **Boundary — single story.** Epic with only\n   `story-XXXX-0001`; 1 phase with 1 story; critical path length 1.\n3. **Error — cyclic dependency.** Synthetic epic A→B, B→A; exit 3;\n   stderr contains `CYCLIC_DEPENDENCY`.\n4. **Error — epic dir missing.** `--epic-id 9999`; exit 1.\n5. **Error — map missing.** Epic dir exists without\n   `IMPLEMENTATION-MAP.md`; exit 2.\n6. **Error — story file missing.** Map references\n   `story-XXXX-0099.md` but file absent; exit 4.\n7. **Parallel — overlap computed.** Two stories in the same phase\n   touching the same file; `overlapMatrix` populated;\n   `overlapSeverity` matches RULE-004 classification.\n\nCoverage requirement: ≥ 95% line \u002F ≥ 90% branch across the\nparser, DAG, overlap matrix, and envelope-assembly logic. Goldens\n(if added) lock the SKILL.md rendering under\n`src\u002Ftest\u002Fresources\u002Fgolden\u002Finternal\u002Fplan\u002Fx-internal-build-epic-plan\u002F`\nper the sibling pattern (story-0049-0012, story-0049-0014).\n\n## Generator Filter Contract\n\nThe `ia-dev-env` generator MUST exclude skills with\n`visibility: internal` from:\n\n1. The `.claude\u002FREADME.md` skill-inventory table.\n2. The `\u002Fhelp` menu listing surfaced by Claude Code.\n3. User-facing autocomplete in the chat input.\n\nInternal skills are still copied into `.claude\u002Fskills\u002F` (flat\nlayout) so `Skill(skill: \"x-internal-…\")` invocations from other\nskills resolve correctly. The invariant: **user cannot see them;\norchestrators can invoke them.**\n\n## Telemetry\n\nInternal skills DO NOT emit `phase.start` \u002F `phase.end` markers —\ntelemetry is produced by the invoking orchestrator (the `phase`\nwrapping the orchestrator's own step is the correct aggregation\nboundary). Passive hooks still capture `tool.call` for each\nunderlying `Skill` \u002F `Bash` invocation made from inside the skill\nbody.\n\nReference: Rule 13 (Skill Invocation Protocol), Rule 22 (Lifecycle\nIntegrity Audit), ADR-0010 (Interactive Gates Convention — exempts\ninternal skills from the 3-option menu contract), ADR-0006\n(File-Conflict-Aware Parallelism — defines RULE-004 hotspot table\nand RULE-006 footprint-unknown advisory).\n\n## Integration Notes\n\n| Skill | Relationship | Context |\n| :--- | :--- | :--- |\n| `x-implement-epic` | caller (primary) | Phase 0 \u002F 0.5 carve-out: ~250 inline lines collapse to one `Skill(skill: \"x-internal-build-epic-plan\", …)` invocation in story-0049-0018 |\n| `x-internal-write-report` | delegate (Step 6) | Renders `epic-execution-plan.md` using `_TEMPLATE-EPIC-EXECUTION-PLAN.md`; defined in story-0049-0006 (MERGED) |\n| `x-evaluate-parallelism` | downstream peer | Phase 1.5 of the caller consumes the `overlapMatrix` to compute per-wave collision classification (EPIC-0041) |\n| `x-internal-update-status` | peer | Separate concern (mutates state); never invoked from this skill |\n| `x-internal-load-story-context` | peer | Sibling read-only carve-out at the story level; never invoked from this skill |\n| `x-internal-build-story-plan` | peer | Sibling story-level planning carve-out; never invoked from this skill |\n\nDownstream stories that depend on this carve-out:\nstory-0049-0018 (`x-implement-epic` refactor consumes the envelope\nand deletes the inline Phase 0 \u002F 0.5 blocks).\n\nFull workflow detail (parser grammar for the IMPLEMENTATION-MAP\ndependency table, Kahn-algorithm pseudocode, footprint-block regex,\noverlap-severity decision table, and the `x-internal-write-report`\nstdin schema) lives in\n[`references\u002Ffull-protocol.md`](references\u002Ffull-protocol.md)\nper ADR-0011.\n",{"name":5,"category":24,"visibility":25,"description":7,"allowed-tools":26,"argument-hint":27,"context-budget":28,"user-invocable":20,"requires-capabilities":29},"internal-plan","internal","Bash, Skill","--epic-id \u003CXXXX> --mode \u003Csequential|parallel> --output \u003Cpath> [--strict-overlap]","heavy",[],"main","952a630c6f38d193a349d86fa18db1de8843e837","src\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring-fintech-pci\u002F.claude\u002Fskills\u002Fx-internal-build-epic-plan",1,"https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment","https:\u002F\u002Fgithub.com\u002Freview-bench","https:\u002F\u002Freview-bench.ai","An open benchmark for AI code review.","2026-10-27 06:56:37",{"source":8,"skillName":5,"commands":40,"prompt":50,"zipAvailable":51},[41,44,47],{"tool":42,"command":43},"npx","npx skills add review-bench\u002Federcnj_ia-dev-environment --skill x-internal-build-epic-plan",{"tool":45,"command":46},"bunx","bunx skills add review-bench\u002Federcnj_ia-dev-environment --skill x-internal-build-epic-plan",{"tool":48,"command":49},"pnpm","pnpm dlx skills add review-bench\u002Federcnj_ia-dev-environment --skill x-internal-build-epic-plan","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring-fintech-pci\u002F.claude\u002Fskills\u002Fx-internal-build-epic-plan\u002FSKILL.md",true,[53],{"path":54,"resourceType":55,"resourceTypeDesc":56,"sizeBytes":57,"sourceHtmlUrl":58},"references\u002Ffull-protocol.md","REFERENCE","参考文档",11964,"https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring-fintech-pci\u002F.claude\u002Fskills\u002Fx-internal-build-epic-plan\u002Freferences\u002Ffull-protocol.md",[60,67,74,81,88,95],{"skillNo":61,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":64,"categories":65,"keywords":66,"publishedAt":19},"01M757M8J48TQ1Y3X25GSJBXAS","x-parallel-eval","Detects and classifies file-collision risks between work units (tasks, stories, or epic phases) before parallel execution. Reads ## File Footprint blocks produced by x-task-plan \u002F x-story-plan, applies the parallelism-heuristics knowledge pack (hard \u002F regen \u002F soft categories + hotspot overrides), and emits a collision matrix + serialization recommendation in Markdown (default) or JSON.","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fx-parallel-eval\u002FSKILL.md",[],[],{"skillNo":68,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":19},"01M757M57XMR9546S69466HDWT","parallelism-heuristics","Canonical catalog of file-collision heuristics for parallel task, story, and epic execution. Defines the File Footprint block format, the three Conflict Categories (hard \u002F regen \u002F soft), a hotspot list of high-contention paths, and the degrade-with-warning policy. Consumed by x-task-plan, x-story-plan, x-epic-map, x-parallel-eval, and x-dev-*-implement.","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fparallelism-heuristics\u002FSKILL.md",[],[],{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":19},"01M757M11SZ8P1VCQABT08QVYA","x-watch-pr-ci","Polls a PR's CI checks and Copilot review status, blocking until checks complete or timeout. Returns one of 8 stable exit codes (SUCCESS=0, CI_PENDING_PROCEED=10, CI_FAILED=20, TIMEOUT=30, PR_ALREADY_MERGED=40, NO_CI_CONFIGURED=50, PR_CLOSED=60, PR_NOT_FOUND=70). Writes a versioned state-file for session resume.","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring\u002Fplatform-claude-code\u002F.claude\u002Fskills\u002Fx-watch-pr-ci\u002FSKILL.md",[],[],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":19},"01M757KW53K8KFPGADFB4PH949","x-validate-docs","Documentation freshness gate: validates 6 dimensions (readme, api-specs, grpc-proto, adr, skill-docs, system-architecture) against code changes in a PR. Stack-aware — only validates targets declared\u002Fauto-detected from ProjectConfig.documentation.targets. Returns exit non-zero on staleness; produces structured report.","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring\u002Fplatform-claude-code\u002F.claude\u002Fskills\u002Fx-validate-docs\u002FSKILL.md",[],[],{"skillNo":89,"name":90,"nameZh":6,"description":91,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":19},"01M757KQZHSA10MKC0CR571D60","x-update-system-architecture","Incrementally updates docs\u002Farchitecture\u002Fsystem.md after an epic completes. Appends new entries to the Decision Log (§11) using x-internal-write-report --append (dedup by ## ID: marker) and surgically inserts component\u002Fintegration changes into sections 1-10 via Edit. Idempotent: re-running with the same epic produces a byte-identical system.md.","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring\u002Fplatform-claude-code\u002F.claude\u002Fskills\u002Fx-update-system-architecture\u002FSKILL.md",[],[],{"skillNo":96,"name":97,"nameZh":6,"description":98,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":99,"categories":100,"keywords":101,"publishedAt":19},"01M757KKBT5Q1SVF8DMJBVF46M","x-update-architecture","Incrementally updates the service architecture document with changes from architecture plans. Adds new components, integrations, flows, and ADR references without rewriting existing content. Use after implementation to keep architecture documentation current.","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring\u002Fplatform-claude-code\u002F.claude\u002Fskills\u002Fx-update-architecture\u002FSKILL.md",[],[]]