agile-initiative-progress

name	agile:initiative:progress
description	Track realization + implementation progress for an initiative. Scans the initiative's Epic Candidates table, cross-references with agile/epics/ to find realized epics (accepts canonical `initiative:` frontmatter and legacy prose backlinks), scans each realized epic's tasks.md for 6-state marker counts, and writes a regenerable `agile/initiatives/NNN-name/progress.md` with realization table, per-epic completion %, and unrealized backlog. Use when the user asks about initiative progress, initiative status, "how far along is the initiative", wants a cross-epic dashboard, or mentions the initiative's planned epics vs. realized ones. Triggers on "initiative progress", "initiative status", "how far along is initiative", "initiative dashboard", "check initiative", "refresh initiative progress".
user-invocable	true
allowed-tools	Read, Write, Bash, Glob, Grep, AskUserQuestion

Initiative Progress

Produce a dashboard of an initiative's realization + implementation progress. This skill is read-only over epic artifacts — it never edits tasks.md, spec.md, or any epic's design.md. The only file it writes is agile/initiatives/NNN-name/progress.md, which is fully regenerable.

Invocation

/agile:initiative:progress <slug-or-number>

# Examples
/agile:initiative:progress 001
/agile:initiative:progress 001-staging-runtime-recovery
/agile:initiative:progress            # interactive: asks user to pick from agile/initiatives/

When to use

• You want to know "which epics from this initiative are done?" without reading 8 separate tasks.md files.
• You want a single markdown file (committed to the repo) that shows realization + implementation progress.
• You want the initiative's "closeout readiness" view (overall % + unrealized backlog).

When NOT to use

• You want to modify epic artifacts (tasks.md, spec.md, epic.md) — use agile-epic-progress instead.
• You want to push work items to Azure DevOps — this skill does NOT touch DevOps.
• You only need to look at a single epic's progress — use agile-epic-progress.

Phases

Phase 1: Resolve initiative

• If an argument was provided, resolve it to a directory under agile/initiatives/. Accept either the slug (001-staging-runtime-recovery) or the number (001 or 1).
• If no argument, use AskUserQuestion to list the available initiatives (one per agile/initiatives/NNN-*).
• If the initiative directory does not contain design.md, report the error and stop.

Phase 2: Compute

Run the script:

python3 .claude/skills/agile-initiative-progress/scripts/compute-initiative-progress.py <slug> \
  [--repo-root <path>] [--write] [--out <path>]

Default behavior (no --write): emit the rendered markdown to stdout. With --write: also write to agile/initiatives/<slug>/progress.md. With --out <path>: write to a custom path instead of the default.

The script internally reuses ../agile-epic-brainstorm/scripts/scan-initiative-epics.py for candidate↔epic matching, then scans each realized epic's tasks.md files for 6-state marker counts.

Phase 3: Present

1. Display the generated markdown to the user.

2. Use AskUserQuestion to ask whether to write the file:

   • Write progress.md (Recommended) — runs with --write
   • Display only — don't write — skip writing
   • Abort

3. If written, report the path. Do NOT commit — the user chooses whether to commit.

Progress computation

6-state markers

Task state characters recognized in tasks.md (Epic-Progress convention):

Marker	Meaning	Counted as
[ ]	pending	incomplete
[W]	working	incomplete
[X]	done	complete
[B]	blocked	incomplete
[S]	skipped	excluded
[-]	skipped (alt)	excluded

Completion percentage per epic = done / (total - skipped) × 100.

Aggregation

Metric	Formula
Realization %	realized_count / (total_candidates - retired_count) × 100
Implementation %	Weighted mean of realized-epic completion %. Unrealized candidates treated as 0 % (pulls the mean down).
Overall %	Realization × Implementation / 100 — the honest single number

Retired candidates are excluded from all denominators (they are not expected to be realized).

Output format

Generated progress.md follows templates/progress-template.md. Sections:

• Summary: initiative name, status, timestamp, 3 headline percentages
• Realization Table: one row per candidate with Seq, Name, Realized Epic, Epic Status, Tasks, %
• Orphan Epics (if any): epics that backlink to the initiative but don't match a candidate
• Unrealized Backlog: actionable list of candidates still to brainstorm
• Footer: regeneration command + generated-from commit SHA

Scripts

Script	Purpose
scripts/compute-initiative-progress.py	Scan, aggregate, and render progress.md

Templates

Template	Purpose
templates/progress-template.md	Markdown skeleton used by the compute script

Related skills

• agile-epic-brainstorm Phase 1.5 uses the same scan script to detect already-realized candidates before starting a new epic brainstorm.
• agile-epic-progress drives per-epic tasks.md ↔ spec.md ↔ epic.md sync and DevOps push. This skill does not duplicate that work — it only reads.

Safety

• NEVER edit files under agile/epics/ — only read.
• NEVER push to DevOps.
• The ONLY file this skill may write is agile/initiatives/<slug>/progress.md (or the --out path if provided).
• If the initiative cannot be resolved or its design.md is missing, fail loudly with the error; do not create a stub file.