agile-initiative-pack

name	agile:initiative:pack
description	Pack every markdown artifact in an initiative folder (design.md, refinement-report.md, progress.md) PLUS the full pack for every realized epic in the initiative (invoking agile:epic:pack for each epic in ascending order) into a single NotebookLM-ready source document at NNN-pack.md, then strictly validate that no content was lost in translation. Use this whenever the user wants to combine initiative artifacts for Google NotebookLM ingestion, generate a single source for Gemini-based infographic / slide deck / video presentation creation covering the whole multi-epic program, prepare an initiative for stakeholder briefing material, or asks to "pack", "combine", "bundle", "consolidate", or "flatten" an initiative's documentation. Strict validation blocks the commit on any context loss.
user-invocable	true
disable-model-invocation	true
allowed-tools	Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Skill

Initiative Pack

Combine every markdown artifact in an initiative folder, plus the full per-epic pack for every realized epic in the initiative, into a single NotebookLM-optimized source document. Strictly validate the result so Gemini can generate infographics, slide decks, and video presentations covering the whole program from one source without silent context loss.

Invocation

• /agile:initiative:pack — auto-detect a target initiative in agile/initiatives/
• /agile:initiative:pack 004 — target initiative 004
• /agile:initiative:pack agile/initiatives/004-legacy-financial-accounting-migration — target a specific path

Optional flags (append after the identifier):

• --no-include-epics — skip the per-epic pack step and produce a lightweight initiative-only pack (the pre-2026-04-24 behavior)
• --force-repack-epics — re-invoke /agile:epic:pack even when an epic's NNN-pack.md is newer than every source artifact in the epic
• --max-words N — raise the NotebookLM size limit for very large combined packs (default 500000; initiatives with many rich epics may legitimately need more)

Context

• Current branch: !git branch --show-current
• Recent initiatives: !ls agile/initiatives/ 2>/dev/null | sort | tail -10

Why this skill exists

Initiative artifacts live as up to three top-level files: design.md (always present, the strategic spec), refinement-report.md (when the expert panel was run via /agile:initiative:refine), and progress.md (the regenerable cross-epic dashboard). Each realized epic under the initiative also has its own rich artifact tree (epic.md, design.md, plan.md, checklist.md, and every feature's spec.md + tasks.md), which the sibling agile:epic:pack skill flattens into its own NNN-pack.md.

NotebookLM can technically take many sources per notebook, but Gemini produces dramatically better outputs (audio overview, mind map, slide deck, video presentation, infographic) when given a single, well-structured source with explicit cross-section navigation. Multi-source notebooks fragment Gemini's outline extraction and break cross-references.

This skill produces that single source for the entire multi-epic program — strategy first, then each epic's full pack in ascending epic-number order — deterministically, and then validates it strictly so the user can be confident that nothing was dropped, truncated, or silently rewritten.

Scope boundary: the combined pack covers only realized epics (those that exist as directories under agile/epics/NNN-slug/ and backlink to this initiative). Unrealized Epic Candidates from the initiative's design.md are mentioned in prose but not inlined. Use --no-include-epics if you want a short, initiative-only pack (e.g., for an exec-level briefing where the per-epic detail is not needed).

Phases

• Phase 1: Resolve initiative directory, discover realized epics, verify prerequisites
• Phase 2: Pack each realized epic in ascending order via agile:epic:pack
• Phase 3: Build the combined initiative pack via scripts/pack.py --append-epic-packs
• Phase 4: Strict validation via scripts/validate.py --epic-packs
• Phase 5: Present results to the user and offer commit

Phase 1: Resolve & Discover

1. Resolve INIT_DIR:

   • If $ARGUMENTS contains a 3-digit number (e.g. 004): match a directory in agile/initiatives/ whose name starts with that prefix.
   • If $ARGUMENTS contains a path: use it directly (must exist).
   • If no positional argument: list candidates in agile/initiatives/ that contain design.md. If exactly one is in the current branch context, use it. Otherwise use AskUserQuestion to let the user choose from the most-recently-modified candidates.

2. Hard prerequisites (exit with a clear error if any fails):

   • INIT_DIR/design.md exists. Initiatives without a design are malformed; nothing else makes sense to pack.

3. Soft warnings (do not block, but report):

   • refinement-report.md missing → the expert-panel refinement was never run (or was rolled back). Pack will still proceed with just the design.
   • progress.md missing → the realization dashboard hasn't been generated yet. Suggest running /agile:initiative:progress NNN first if the user wants the latest progress in the pack.

4. Discover realized epics (skip entirely if --no-include-epics was passed):

   python3 .claude/skills/agile-initiative-pack/scripts/discover-epics.py INIT_DIR_OR_ID
   

   The helper scans every agile/epics/*/design.md, keeps those that backlink to the initiative (either a initiatives/<slug> path-style link or a bare slug following an **Initiative**: label), and emits a JSON list sorted ascending by epic number. Each entry also reports pack_exists and pack_fresh (the latter is true only when NNN-pack.md is newer than every source file in the epic). This lets the next phase skip already-fresh epic packs.

   If zero epics are discovered and --no-include-epics was not passed, inform the user and offer three choices via AskUserQuestion:

   • "Proceed with initiative-only pack" (sets the skip flag for downstream phases)
   • "Cancel — no epics to include"
   • "Open the discover-epics output so I can debug"

Phase 2: Pack Each Epic

Skip this phase entirely if --no-include-epics was passed or if discovery returned zero epics.

For each entry from the discovery JSON, in the order they appear (ascending epic number):

1. Decide whether to invoke agile:epic:pack:

   • If pack_fresh is true AND --force-repack-epics was NOT passed: reuse the existing pack_path, report "reused fresh epic NNN pack", and move on.
   • Otherwise: invoke the agile:epic:pack skill via the Skill tool, passing the epic's 3-digit number as the argument. That skill runs its own four-phase workflow and writes NNN-pack.md into the epic directory. When agile:epic:pack prompts about committing the produced file, answer "Done — leave uncommitted" — committing is the initiative pack skill's responsibility at Phase 5 so the reviewer sees a single atomic change.

2. Collect the resulting epic-pack path (always <epic_dir>/<NNN>-pack.md). Keep an ordered list EPIC_PACK_PATHS for Phase 3.

3. If agile:epic:pack fails for any epic (returns a non-zero exit or reports a validation failure): stop immediately, surface the failure verbatim, and offer via AskUserQuestion:

   • "Fix the failing epic first, then rerun"
   • "Skip this epic and continue with the remaining ones" (the skipped epic's pack will not be included in the combined pack)
   • "Abort the initiative pack entirely"

Phase 3: Build the Combined Pack

Run the initiative packer with every epic pack path appended (omit the flag entirely if Phase 2 was skipped):

python3 .claude/skills/agile-initiative-pack/scripts/pack.py \
    --init-dir INIT_DIR \
    --append-epic-packs EPIC_PACK_PATHS...

The packer writes INIT_DIR/NNN-pack.md. Its stdout reports the source count, appended epic count, and output word + byte counts. Capture this for the final report.

If the packer exits non-zero, surface stderr verbatim and stop. Do not proceed to validation.

Phase 4: Strict Validation

Run the validator in strict mode, passing the same epic pack paths so the preservation checks cover the appended content:

python3 .claude/skills/agile-initiative-pack/scripts/validate.py \
    --init-dir INIT_DIR \
    --pack INIT_DIR/NNN-pack.md \
    --epic-packs EPIC_PACK_PATHS... \
    --strict

(If Phase 2 was skipped, omit --epic-packs — the validator then runs with only the initiative-level sources.)

The validator runs eight checks against the freshly written pack:

#	Check	What it guarantees
1	content-coverage	Every non-heading content line from every source (initiative artifacts + every appended epic pack) appears verbatim in the pack
2	heading-preservation	Pack contains at least as many headings as the sum of source headings across all inputs
3	table-preservation	Every table row from every source is preserved
4	code-fence-preservation	Code fence count is preserved (so ASCII DAGs survive intact)
5	metadata-preservation	Every **FieldName**: metadata line (Status, Refined dates, DevOps IDs, etc.) is preserved
6	cross-reference-rewriting	No unrewritten design.md / refinement-report.md / progress.md references remain outside code fences
7	word-count-sanity	Pack word count ≥ 95% of the sum of source word counts
8	notebooklm-size-limit	Pack word count is below the hard limit (default 500000; override via --max-words)

On failure (validator exits 1):

• Show the validator's full report to the user.
• Identify whether the failure is in pack.py (a code bug — the source content exists but the script dropped it), in the source artifacts (an unusual structure the script doesn't yet handle), or in an epic pack that was itself malformed (e.g. came from an older agile-epic-pack version).
• Use AskUserQuestion to present options:
  • "Diagnose and fix the packer", "Diagnose and rebuild the offending epic pack", "Skip validation and write the pack anyway (NOT recommended)", "Abort"
• Do NOT auto-commit on validation failure.

On success (validator exits 0):

• Show the validator's summary report (one PASS line per check) so the user can see exactly what was checked.
• Proceed to Phase 5.

Phase 5: Present & Commit

1. Print a summary block:

   Initiative Pack Complete
   
   Source: INIT_DIR
   Pack:   INIT_DIR/NNN-pack.md
   Sources packed: M of 3 possible initiative artifacts + K epic pack(s)
   Epic packs:
     - Epic NNN: <title>    (fresh | repacked)
     - Epic NNN: <title>    (fresh | repacked)
     ...
   Pack size: X words / Y bytes
   
   Validation:
     [PASS] content-coverage         (no missing lines)
     [PASS] heading-preservation     (P pack / Q source headings)
     [PASS] table-preservation       (R rows preserved)
     [PASS] code-fence-preservation  (S fences preserved)
     [PASS] metadata-preservation    (T metadata lines preserved)
     [PASS] cross-reference-rewriting (no dangling .md refs)
     [PASS] word-count-sanity        (ratio Z)
     [PASS] notebooklm-size-limit    (X / limit words)
   
   Next: upload NNN-pack.md to a new NotebookLM notebook as the only source,
         then generate audio overview → mind map → slide deck → video.
   

2. Use AskUserQuestion to ask:

   • Question: "Pack written and validated. What would you like to do next?"
   • Options:
     • "Commit the initiative pack and all newly-produced epic packs" — a single git commit that stages INIT_DIR/NNN-pack.md plus every epic NNN-pack.md that Phase 2 produced or refreshed. Message: docs(agile): add NotebookLM pack for initiative NNN (K epics).
     • "Commit only the initiative pack" — stage just INIT_DIR/NNN-pack.md; leave epic packs uncommitted for a separate review.
     • "Open the pack for review first" — print the path and stop.
     • "Done — leave uncommitted" — print the path and stop.

3. If the user picks a commit option, run the git commands and report the new commit hash.

Key Principles

• Deterministic packer: pack.py is pure text transformation. The same inputs always produce the same output. There is no LLM in the packing path so the result is reproducible and easy to debug.
• Delegate to agile:epic:pack for epic content: the initiative pack skill never re-implements epic packing. It invokes the sibling skill via the Skill tool and trusts the file it produces. This keeps the per-epic validation discipline intact and means improvements to the epic packer automatically improve initiative packs too.
• Fresh-pack skipping saves serious time: initiatives with many realized epics would take minutes to repack every time otherwise. The discover-epics.py helper compares NNN-pack.md mtime to every epic-source mtime; only stale packs are rebuilt. --force-repack-epics overrides this when you explicitly want a clean rebuild.
• Strict validation by default: silent context loss is the worst failure mode for this skill — Gemini will happily generate confident, polished slides about content that was dropped. The validator's job is to make that impossible, and it treats every appended epic pack as an additional source for preservation checks.
• Single H1, demoted hierarchy: the pack has exactly one H1 (the initiative title). Source H1s are demoted to H2; each inlined epic pack's H1 becomes an H2 section ("Epic NNN: ") with all its inner headings demoted one more level. NotebookLM uses heading hierarchy as the primary signal for outline / slide / mind-map generation, so a clean hierarchy directly improves output quality.
• Anchors, not file paths (at the initiative level): initiative-level cross-references ("see refinement-report.md") become anchor links so the pack reads top-to-bottom. Epic-pack internal anchors are left as the epic packer produced them — they resolve within each epic's own section and don't need to cross-link with the initiative content.
• ASCII DAGs stay in code fences: process maps and any whitespace-aligned diagrams are only preserved by NotebookLM inside fenced code blocks. The packer never lifts content out of fences.
• Bridge paragraphs help video output: short narrative bridges between major sections (initiative → epics, and between each epic series) give Gemini natural transition points; video narrations come out noticeably more coherent with them.
• The 500k word limit is real but overridable: NotebookLM truncates oversized sources silently. Initiative-only packs rarely approach this; combined packs for 8+ epic initiatives routinely will. Pass --max-words with a number you know the current NotebookLM ingest accepts (empirically up to ~900k has worked), or split the pack by producing a subset pack with --no-include-epics and per-epic packs consumed separately.

Scripts

Script	Purpose	Inputs	Output
scripts/discover-epics.py	Find every realized epic backlinked to an initiative and compute pack freshness	positional initiative identifier (number / slug / path)	JSON (default) or text table to stdout
scripts/pack.py	Combine initiative artifacts + appended epic packs into one markdown file	--init-dir, optional --output, optional --append-epic-packs	Writes NNN-pack.md; prints summary to stdout
scripts/validate.py	Strict context-preservation validation	--init-dir, --pack, optional --epic-packs, optional --max-words, --strict	Exit 0 = pass, 1 = fail; report on stdout

References

File	Purpose
references/notebooklm-optimization.md	Background on how NotebookLM/Gemini ingests markdown sources, why the pack is structured the way it is, common failure modes, and tips for the post-pack NotebookLM workflow. Read this when debugging unexpected NotebookLM output, or when adjusting the packer for new artifact types.

Related skills

Skill	Relationship
agile:epic:pack	Invoked by Phase 2 once per realized epic. Produces agile/epics/NNN-slug/NNN-pack.md, which is then appended into this skill's output.
agile:initiative:progress	Regenerates progress.md; run it before this skill if you want a fresh realization dashboard inside the pack.
agile:initiative:refine	Produces refinement-report.md (phase-3.5 expert-panel review). This skill includes that file if present.

Terminal State

The terminal state is a written, validated NNN-pack.md in the initiative root that contains the initiative's own artifacts plus the full pack for every realized epic (or just the initiative artifacts when --no-include-epics was used). Epic packs produced along the way sit as agile/epics/NNN-slug/NNN-pack.md files and may be committed with the initiative pack or left uncommitted per the user's choice. This skill does NOT upload to NotebookLM, generate any infographic / slide deck / video, or invoke any other skill beyond agile:epic:pack — the NotebookLM workflow is an external step the user takes manually with the produced file.