briefing

name: briefing argument-hint: "[report [period]] | verify | current | worktrees | [summary] | [every SCHEDULE] | stop | next" description: >- Generate a project briefing: worktree status, open checkboxes, recent commits. Modes: summary (default), report, verify, current, worktrees. Period: 1h, 6h, 24h, 2d, 7d. metadata: version: "2026.06.15+e3e5e2"

/briefing — Project Status Briefing

Gather project state and present a structured briefing.

Runtime

The briefing helper is "$PYTHON" "$ZSKILLS_SKILLS_ROOT/briefing/scripts/briefing.py" (resolve $PYTHON by sourcing the config prelude first, as every fenced block below does — a bare python3 is the broken MS Store stub on Windows, #1083). Python 3 is required (per CLAUDE.md "Python is required"). If no working Python 3 is found ($PYTHON empty), output a clear error and stop:

/briefing requires Python 3. Install it and ensure it's on PATH. Python: https://python.org/

Argument Parsing

Parse $ARGUMENTS to determine mode, options, and optional schedule:

$ARGUMENTS = ""              → mode: summary
$ARGUMENTS = "summary"       → mode: summary
$ARGUMENTS = "report"        → mode: report, period: 24h
$ARGUMENTS = "report 7d"     → mode: report, period: 7d
$ARGUMENTS = "verify"        → mode: verify
$ARGUMENTS = "current"       → mode: current
$ARGUMENTS = "worktrees"     → mode: worktrees
$ARGUMENTS = "stop"          → meta: cancel scheduled briefings
$ARGUMENTS = "next"          → meta: show next scheduled briefing
$ARGUMENTS = "report 24h every day at 9am" → mode: report, schedule

Period shorthand: 1h, 6h, 24h (default), 1d, 2d, 7d

Schedule detection: If $ARGUMENTS contains every <SCHEDULE>, strip the schedule portion and handle scheduling separately (see Scheduling section below).

Mode Dispatch

CRITICAL: "Present verbatim" means OUTPUT EVERY LINE. Do not summarize, collapse, truncate, or rephrase script output. The script's formatting IS the presentation — it was designed to be read directly. If the output is 50 lines, show 50 lines. The user wants to SEE the data, not hear about it. Past failure: agent received 45 lines of worktree status and collapsed it to a 4-line summary, hiding actionable details like which logs need extraction and which commits are unlanded.

summary (default — empty or unrecognized arguments)

Quick terminal-only triage view. The helper outputs pre-formatted text.

if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh" ]; then
  export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
  . "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh"
else
  . "$CLAUDE_PROJECT_DIR/.claude/skills/update-zskills/scripts/zskills-resolve-config.sh"
fi
"$PYTHON" "$ZSKILLS_SKILLS_ROOT/briefing/scripts/briefing.py" summary --since=<period>

Present the output verbatim — it is already formatted with three buckets:

• NEEDS ATTENTION — worktrees needing review, unchecked checkboxes, uncommitted files
• LANDED SINCE LAST 24H — recent commits grouped by conventional type
• IN FLIGHT — possibly-active worktrees, stash entries
• QUIET — count of landed/empty worktrees (no action needed)
• WARNINGS — staleness warnings if applicable

report

Generate a detailed markdown report and write it to $ZSKILLS_AUDIT_DIR/.

if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh" ]; then
  export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
  . "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh"
else
  . "$CLAUDE_PROJECT_DIR/.claude/skills/update-zskills/scripts/zskills-resolve-config.sh"
fi
"$PYTHON" "$ZSKILLS_SKILLS_ROOT/briefing/scripts/briefing.py" report --since=<period>

The helper writes the file directly and prints its path. Report includes:

• Summary counts (commits, worktrees, checkboxes)
• Needs Attention section with review checklists
• Landed on Main table
• Worktree Status table
• In Progress section

Checkbox state from earlier same-day reports is preserved automatically.

Present: "Report written to: <path>" with a brief summary of key findings.

verify

Purpose: show the user everything they need to verify, with links to open the reports directly. This is a sign-off dashboard — the user reads this, clicks through, checks items off, done.

This mode is NOT about worktrees. Do not mention worktrees, do not suggest the user verify worktrees before landing, do not include worktree counts or status. Worktrees are for /briefing worktrees. Verify is exclusively about report checkboxes — [ ] items in verification reports, fix reports, and plan reports that need human sign-off.

Step 1 — Gather data

if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh" ]; then
  export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
  . "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh"
else
  . "$CLAUDE_PROJECT_DIR/.claude/skills/update-zskills/scripts/zskills-resolve-config.sh"
fi
"$PYTHON" "$ZSKILLS_SKILLS_ROOT/briefing/scripts/briefing.py" verify

The script output includes both report sign-off data and worktree data. Use both — report checkboxes are the primary output, worktrees needing verification are secondary (see "Worktree verification items" below).

Step 2 — Read the actual report files

The script gives file paths and counts. That's not enough — the user needs to see the actual checkbox text. For each report file with unchecked items, READ the file and extract every [ ] line with its surrounding context (the heading it's under, any verification instructions).

Step 3 — Build the output with file references

For each report file, include the file path so the user can open it.

Present the output in this format:

Pending sign-offs: N items across M reports

$ZSKILLS_AUDIT_DIR/FIX_REPORT.md — 33 items
  $ZSKILLS_AUDIT_DIR/FIX_REPORT.md

  UI / UX Fixes:
    [ ] Feature X verification — exercise primary flow, confirm expected output
    [ ] Edge case Y handling — trigger boundary input, verify graceful fallback

  Simulation Fixes:
    [ ] Solver tolerance — run sample case, verify output within 1e-6

$ZSKILLS_REPORTS_DIR/plan-feature-expansion.md — 9 items
  $ZSKILLS_REPORTS_DIR/plan-feature-expansion.md

  Phase 1:
    [ ] Feature X verification
    [ ] Component Y wiring works

$ZSKILLS_AUDIT_DIR/VERIFICATION_REPORT.md — 2 items
  $ZSKILLS_AUDIT_DIR/VERIFICATION_REPORT.md

  [ ] Edge case Z sign-off
  [ ] Migration sanity check

Key formatting rules:

• The terminal output is a DIRECTORY, not a replica. Show the report name, item count, file path, and section summaries — not every checkbox line. The user opens the file to do the actual sign-off work.
• Group by report file, with section summaries (e.g., "UI / UX Fixes: 5 items", "Simulation: 3 items")
• The file path is the actionable part — make it prominent

Worktree verification items

If the script's output includes worktrees needing verification before landing, include them — they ARE verification items. But flag them as unusual: a worktree needing user verification at /briefing verify time means /run-plan or /fix-issues didn't complete its verification phase.

⚠ Worktree needing verification (suggests incomplete skill run):
  agent-a5217dbd (SLX Export Phase 1) — 6 commits, not yet verified/landed

This surfaces the problem rather than hiding it.

Empty state: ALL CLEAR — no pending sign-off items.

current

Show what's actively in flight right now.

if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh" ]; then
  export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
  . "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh"
else
  . "$CLAUDE_PROJECT_DIR/.claude/skills/update-zskills/scripts/zskills-resolve-config.sh"
fi
"$PYTHON" "$ZSKILLS_SKILLS_ROOT/briefing/scripts/briefing.py" current

Present the output verbatim. Sections:

• POSSIBLY ACTIVE — worktrees modified in last 2 hours
• FINISHED, NOT LANDED — worktrees with commits, inactive > 2h
• EMPTY WORKTREES — zero commits, safe to remove
• UNCOMMITTED ON MAIN — modified/deleted/untracked file counts
• STASH — git stash entries or "(empty)"
• LONG-RUNNING BRANCHES — named worktrees with commits ahead of main

worktrees

Detailed worktree analysis with cleanup readiness. Read-only — shows what's safe to remove but does not remove anything.

if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh" ]; then
  export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
  . "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh"
else
  . "$CLAUDE_PROJECT_DIR/.claude/skills/update-zskills/scripts/zskills-resolve-config.sh"
fi
"$PYTHON" "$ZSKILLS_SKILLS_ROOT/briefing/scripts/briefing.py" worktrees-status

Present the output verbatim. Sections:

• SAFE TO REMOVE — empty worktrees or all commits verified on main, no unextracted logs. Includes copy-pasteable git worktree remove commands.
• NEEDS LOG EXTRACTION FIRST — commits are on main but .claude/logs/ has modified files. Shows which logs need extraction and how.
• NOT SAFE — has commits not found on main. Shows unlanded commit list.
• NAMED / LONG-RUNNING — named worktrees (physics module, etc.), never auto-remove.
• ORPHANED — directories on disk but not registered with git worktree list.

Important: Always extract logs before removing any worktree. Logs document how work was done — they are part of the project, not disposable artifacts.

dogfooding

Per-skill SUCCESSFUL-usage measurement (Layer-2 of the skill-verification model — MEASURED reality, not a duplicated test). Display-first; there is deliberately no hard-assert "skill X ran ≥N times" CI gate (it would false-fail on quiet periods).

if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh" ]; then
  export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
  . "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh"
else
  . "$CLAUDE_PROJECT_DIR/.claude/skills/update-zskills/scripts/zskills-resolve-config.sh"
fi
"$PYTHON" "$ZSKILLS_SKILLS_ROOT/briefing/scripts/briefing.py" dogfooding --since=<period>
# --no-gh   disable the gh merged-PR backfill (hermetic / offline runs)

It aggregates two signals, by descending fidelity:

• .zskills/landed markers (strong) — the source: field names the producing skill; status:/ci:/pr_state: distinguish a SUCCESSFUL land (status landed/full, or pr_state: MERGED / ci: pass) from a mere attempt. These are gitignored and live in /tmp worktrees, so this is a rolling on-disk window, not a permanent ledger.
• gh pr list --state merged (weaker, labeled) — durable backfill beyond the on-disk window, but attributes by conventional-commit scope (subsystem), not by skill. The output labels this signal as such; it never overrides a .zskills/landed count.

Source variants are canonicalized to one skill name (e.g. fix-issues, fix-issues-sprint, fix-issues-pr-mode-* → fix-issues). The report emits per-skill landed_count, merged_pr_count, and last_seen, and may flag 0 in <window> per skill as advisory text for a human to read.

Data Gathering

The agent runs "$PYTHON" "$ZSKILLS_SKILLS_ROOT/briefing/scripts/briefing.py" <subcommand> and captures stdout (resolve $PYTHON via the config prelude first — worktrees/checkboxes/commits have no dedicated fenced block, so build the invocation from "$PYTHON", never a bare python3, which is the broken MS Store stub on Windows, #1083).

Worktree Categories

Each worktree is classified into exactly one category:

• landed-full — .zskills/landed file with status: full (fix-issues cherry-pick, all commits on main) or status: landed (run-plan cherry-pick or merged PR)
• landed-partial — .zskills/landed file with status: partial (some commits skipped, needs review)
• landed-pr-ready — .zskills/landed file with status: pr-ready (PR is open; worktree is safe to remove, remote branch must NOT be deleted — it supports the open PR)
• landed-pr-needs-attention — .zskills/landed file with status: pr-ci-failing, status: pr-failed, status: conflict, status: pr-state-unknown, status: failed, status: direct-push-failed, or status: direct-verify-failed (PR-mode or failure-class markers that need manual action)
• done-needs-review — No .zskills/landed, has commits, inactive > 2 hours
• possibly-active — No .zskills/landed, modified within last 2 hours
• empty — No .zskills/landed, zero commits ahead of main
• named — Not an agent-* worktree (e.g., physics module)
• orphaned — Directory exists on disk but not in git worktree list

Scheduling

The /briefing skill supports recurring execution via cron.

Setting a Schedule

If $ARGUMENTS contains every <SCHEDULE>:

1. Strip the schedule portion from arguments to get the base mode
2. Create a cron using CronCreate:
   • cron: parsed from <SCHEDULE> (e.g., "day at 9am" → 3 9 * * *; apply :03/:09 offset per avoid-:00/:30 rule)
   • prompt: Run /briefing <base-mode-args> (the Run / prefix triggers the cron-fire recognition rule in CLAUDE.md ## Cron-fired prompts, so post-/clear sessions execute the briefing inline by reading SKILL.md)
   • recurring: true
3. Present confirmation with session-scope warning:

Scheduled: /briefing <mode> runs every <schedule>

WARNING: This schedule is tied to this session. If the session ends, the schedule is lost.

stop — Cancel Scheduled Briefings

1. List crons with CronList
2. Filter for briefing-related crons (prompt starts with Run /briefing)
3. Delete each with CronDelete
4. Confirm: "Cancelled N briefing schedule(s)."

next — Show Next Fire Times

1. List crons with CronList
2. Filter for briefing-related crons (prompt starts with Run /briefing)
3. Show each with its next fire time
4. If none: "No briefing schedules active."

Common Schedules

Apply :03/:09 minute offsets (avoid :00/:30 per peer pattern):

Report Template Reference

The report subcommand writes this markdown structure:

# Briefing Report — YYYY-MM-DD HH:MM ET
Period: <since> -> now

## Summary
- N commits landed on main
- N worktrees: X need review, Y in flight, Z landed
- N unchecked sign-off items across M reports

## Needs Attention

### [ ] Review: <worktree-name> (N commits)
Commits:
- `hash` subject
Last modified: <relative time>

### [ ] Sign-off: <report-file> (N unchecked items)
- [ ] item text (line NN)

## Landed on Main
| Type | Hash | Subject | Date |
|------|------|---------|------|

## Worktree Status
| Worktree | Category | Commits | Last Modified | Notes |
|----------|----------|---------|---------------|-------|

## In Progress
| Worktree | Commits | Last Modified | Summary |
|----------|---------|---------------|---------|

Checkboxes marked [x] in earlier same-day reports are preserved in new reports.

Staleness Warnings

The summary subcommand appends warnings when:

• No briefing report has ever been generated
• The most recent briefing report is older than 48 hours
• A done-needs-review worktree is older than 7 days (stale)

Z Skills Update Check

If a Z Skills repo clone exists (zskills/ in project root, or /tmp/zskills), the summary and report modes should compare the installed version (resolved from .claude/zskills-config.json via the canonical config-resolution helper) against the source repo's latest release tag:

if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh" ]; then
  export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
  . "${CLAUDE_PLUGIN_ROOT}/skills/update-zskills/scripts/zskills-resolve-config.sh"
else
  . "$CLAUDE_PROJECT_DIR/.claude/skills/update-zskills/scripts/zskills-resolve-config.sh"
fi
# ZSKILLS_VERSION is the installed version (from .claude/zskills-config.json).
source_ver=""
if [ -d "$ZSKILLS_PATH/.git" ]; then
  source_ver=$(bash "$ZSKILLS_SKILLS_ROOT/update-zskills/scripts/resolve-repo-version.sh" "$ZSKILLS_PATH")
fi
if [ -n "$source_ver" ] && [ "$source_ver" != "$ZSKILLS_VERSION" ]; then
  echo "  zskills: $ZSKILLS_VERSION → $source_ver (run /update-zskills)"
else
  echo "  zskills: ${ZSKILLS_VERSION:-(unknown)} (current)"
fi

$ZSKILLS_PATH is the source-clone discovery path (briefing's existing search probes zskills/ in the project root then /tmp/zskills). When no source clone is found, source_ver stays empty and the line falls through to the "current" branch. When the installed version is missing (no zskills_version field in config), the rendered text is zskills: (unknown) (current).

Edge Cases

• Orphaned worktrees — directories in .claude/worktrees/ or worktrees/ not registered with git worktree list. Shown with orphaned category.
• Missing $ZSKILLS_AUDIT_DIR directory — created automatically when writing a report.
• Recency filter — checkbox scanning only checks files modified in last 30 days (or top 10 most recent briefing files) to avoid scanning stale history.