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.

Output

• Chat report: relay the script's own stdout/stderr line verbatim (WORKING: N project(s) -> <path> or BLOCKED: ...) — don't paraphrase it or invent a project count of your own.
• Disk write: the script writes exactly one file, and only the AUTO:STARTAUTO:END region inside it — `/.claude/OVERVIEW.md`. Nothing else on disk is touched, and text outside the markers in that file is never rewritten.
• Final status label: state one of WORKING / PARTIAL / BLOCKED (definitions in Truthful Reporting below) at the end of every run — never leave it implicit.

Scope Boundary

Safety Layers

• L1 (Invariants): Invariant 1 — preserve text outside AUTO markers. Invariant 2 — never scan unregistered projects.
• L3 (User Approval): manual-trigger only — runs only when the user explicitly invokes it (no auto-wiring is itself the approval gate).

Invariants (never violate)

1. Text outside AUTO markers is always preserved: if apply_auto_markers() alters any text outside the markers, that's a bug. Violation → notes a human wrote directly into OVERVIEW.md get lost on re-run.
2. Only scan explicitly registered projects: never add auto directory-discovery logic to this script. Violation → information about unowned projects leaks into the map (Output Disclosure Boundary violation).
3. STATE.md is absolutely untouched: no code path in this skill reads or writes STATE.md. Violation → direct Scope Boundary violation, risk of contaminating the cross-project blocker list.
4. Idempotency: re-running with identical input (unchanged registry + handoff files) must produce a byte-identical AUTO block. Violation → undermines the entire "deterministic auto-generation" design goal.
5. Cross-project text is data, not markup: ts/ctx values come from another project's handoff file and are untrusted — a stray | or newline in there must not be allowed to split table columns or break rows. Violation → a single malformed handoff field corrupts the whole table for every other project listed in it.

Error Recovery

Truthful Reporting

• no mock deception: before reporting "generation complete," actually read OVERVIEW.md to confirm project entries landed in the AUTO block.
• no silent brokenness: a parsing failure for a specific project's handoff is never silently skipped — it's shown explicitly as "no snapshot".
• Final status label: WORKING (generated normally) / PARTIAL (some projects show no snapshot) / BLOCKED (registry missing/empty).

Rationalization Table