project-overview

Project Overview

Dominant Variable

Does the registered project list (projects-registry.md) point to paths that actually exist, and does each project's handoff file contain a state-snapshot v1 block? If neither is true, the generated map is empty.

Key Assumptions

1. session-handoff-LATEST.md is a hint, not a fact — parsed results (ts/ctx) are carried over as-is without fact-checking. The generated overview reflects "what each project last reported," not "current ground truth."
2. Registry is opt-in — never pull in unowned projects or auto-scanned directories. Only projects explicitly listed in projects-registry.md are in scope.
3. AUTO block generation is fully deterministic — a regex-based script (scripts/generate_overview.py) does all the parsing/rendering, including neutralizing markdown-table-breaking characters in the text it pulls from other projects' handoffs, isolating a single non-UTF-8 handoff file so it can't abort the whole run, and refusing (BLOCKED, no write) instead of guessing when the AUTO marker pair itself is mangled. The model only triggers execution and reports the result — no LLM inference in the parsing/rendering logic itself.

Trigger

• /project-overview
• "project map"
• "overall status"

Discard If

• Zero registered projects (projects-registry.md missing or empty list) → instruct the user to add a project to the registry first, then stop
• Already run recently with no state change across projects (handoff file mtimes unchanged) → suggest skipping the re-run (not forced — run if the user wants)

Workflow

1. Confirm ~/.claude/projects-registry.md exists. If missing, return BLOCKED: "registry missing — create it first."
2. Locate and run this skill's own script (scripts/generate_overview.py, no arguments — it uses the default registry/output paths on its own):

   OVERVIEW_SCRIPT=$(find ~/.claude -name "generate_overview.py" -path "*/project-overview/scripts/*" -type f 2>/dev/null | head -1)
   if [ -n "$OVERVIEW_SCRIPT" ]; then
     python "$OVERVIEW_SCRIPT"
   else
     echo "BLOCKED: generate_overview.py not found under ~/.claude"
   fi
   

3. Check the exit code:
   • 0 → report the stdout WORKING: N project(s) -> <output> line verbatim to the user.
   • 1 → report the stderr BLOCKED: ... message verbatim to the user. Never proceed on assumption.
4. On success, tell the user the ~/.claude/OVERVIEW.md path.