@stylusnexus/work-plan 2026.6.9-1

package/skills/work-plan/commands/where_was_i.py

@@ -0,0 +1,325 @@
+"""where-was-i / orient subcommand.
+
+Two modes:
+
+1. With a track name (`/work-plan orient ux-redesign`):
+   Prints a tight ~15-line paste-ready block summarizing where the track stands.
+   Header rule, priority + milestone + repo, track + local paths, last session
+   timestamp + one-line summary, the next pick by issue number + title, up to 3
+   issues behind it, current local-git state, and (if any) new related issues
+   filed since last handoff.
+
+2. With no track name (`/work-plan orient`):
+   Snapshot of the current working directory — branch, ahead-of-upstream count,
+   uncommitted file count, last 3 commits, modified files. Use this when you're
+   working on something that doesn't yet belong to a track.
+
+Add `--pick` to force the interactive track picker instead of cwd-snapshot mode.
+
+No closed/merged dump — that's what the GitHub issue list is for.
+"""
+import re
+import subprocess
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from lib.config import load_config, ConfigError
+from lib.tracks import discover_tracks, find_track_by_name
+from lib.prompts import prompt_input, parse_flags
+from lib.github_state import fetch_issues, short_milestone
+from lib.git_state import (
+    parse_iso_timestamp,
+    current_branch, uncommitted_file_count, commits_ahead,
+)
+from lib.new_issues import build_slug_labels, find_new_issues_for_tracks
+
+
+RULE_CHAR = "─"
+RULE_WIDTH = 57
+
+
+def run(args: list[str]) -> int:
+    flags, positional = parse_flags(args, {"--pick"})
+    track_name = positional[0] if positional else None
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+
+    # Mode 1 (track named): orient on that track.
+    # Mode 2 (--pick): interactive track picker (preserves old default behavior).
+    # Mode 3 (no args, no flag): cwd snapshot.
+    if not track_name and "--pick" not in flags:
+        return _orient_cwd()
+
+    tracks = discover_tracks(cfg)
+
+    if not track_name:
+        # --pick: interactive
+        active = [t for t in tracks if t.has_frontmatter
+                  and t.meta.get("status") in ("active", "in-progress", "blocked")]
+        if not active:
+            print("No active tracks.")
+            return 1
+        print("Active tracks:")
+        for i, t in enumerate(active, 1):
+            print(f"  [{i}] {t.name} ({t.meta.get('launch_priority','P3')})")
+        choice = prompt_input("\nWhich track? (number or name):")
+        if not choice:
+            print("No selection. Cancelled.")
+            return 1
+        if choice.isdigit():
+            idx = int(choice) - 1
+            if not (0 <= idx < len(active)):
+                print("Out of range.")
+                return 1
+            track = active[idx]
+        else:
+            track = find_track_by_name(choice, tracks)
+            if not track:
+                print(f"No track matching '{choice}'.")
+                return 1
+    else:
+        track = find_track_by_name(track_name, tracks)
+        if not track:
+            print(f"No track matching '{track_name}'.")
+            return 1
+
+    return _orient_track(track)
+
+
+def _orient_track(track) -> int:
+    """Render the track paste-block (mode 1)."""
+    slug = track.meta.get("track", track.name)
+    priority = track.meta.get("launch_priority", "P3")
+    milestone = track.meta.get("milestone_alignment", "—")
+    repo = track.repo or "—"
+    next_up = track.meta.get("next_up") or []
+    last_handoff_iso = track.meta.get("last_handoff")
+
+    issue_nums = track.meta.get("github", {}).get("issues") or []
+    titles_by_num: dict[int, str] = {}
+    states_by_num: dict[int, str] = {}
+    milestones_by_num: dict[int, str] = {}
+    if track.repo and next_up:
+        wanted = next_up[:4]
+        fetched = fetch_issues(track.repo, wanted)
+        for i in fetched:
+            titles_by_num[i["number"]] = i.get("title", "")
+            states_by_num[i["number"]] = (i.get("state") or "").upper()
+            milestones_by_num[i["number"]] = short_milestone(i.get("milestone"))
+
+    print(_top_rule(slug))
+    print(f"Priority: {priority}  ·  Milestone: {milestone}  ·  Repo: {repo}")
+    print(f"Track:  {track.path}")
+    if track.local_path:
+        print(f"Local:  {track.local_path}")
+    print()
+
+    last_ts, last_summary = _last_session_summary(track.body)
+    if last_ts:
+        print(f"Last session ({last_ts}):")
+        print(f"  {last_summary}")
+    else:
+        print("Last session: (none yet)")
+    print()
+
+    if next_up:
+        pick_num = next_up[0]
+        pick_title = titles_by_num.get(pick_num, "")
+        pick_suffix = _state_suffix(states_by_num.get(pick_num))
+        pick_ms = _milestone_prefix(milestones_by_num.get(pick_num))
+        print(f"Next pick: #{pick_num}  {pick_ms}{pick_title}{pick_suffix}".rstrip())
+        if _is_closed(states_by_num.get(pick_num)):
+            print(f"  ⚠  next_up:[0] has shipped — run `/work-plan handoff {slug}` to rotate")
+        rest = next_up[1:4]
+        if rest:
+            print()
+            print("Behind it:")
+            for num in rest:
+                title = titles_by_num.get(num, "")
+                suffix = _state_suffix(states_by_num.get(num))
+                ms = _milestone_prefix(milestones_by_num.get(num))
+                print(f"  #{num}  {ms}{title}{suffix}".rstrip())
+    else:
+        print("Next pick: (none set — run `/work-plan handoff` to set one)")
+
+    if track.local_path:
+        cur = current_branch(track.local_path)
+        if cur:
+            ahead = commits_ahead(cur, "dev", track.local_path)
+            uc = uncommitted_file_count(track.local_path)
+            print()
+            print(f"Local: on {cur} ({ahead} ahead of dev, {uc} uncommitted)")
+
+    new_unlisted = _new_issues_since_handoff(track, last_handoff_iso, slug, issue_nums)
+    if new_unlisted:
+        print()
+        print(f"New issues since last handoff ({len(new_unlisted)}):")
+        for i in new_unlisted[:6]:
+            print(f"  #{i['number']}  {i['title']}")
+
+    print(_bottom_rule())
+    return 0
+
+
+def _orient_cwd() -> int:
+    """Render the cwd snapshot (mode 3) — for non-track-bound work."""
+    cwd = Path.cwd()
+    if not _is_git_repo(cwd):
+        print("ERROR: not inside a git repository.")
+        print("       cwd-snapshot mode of orient needs git state to display.")
+        print("       Use `/work-plan orient <track>` for a track paste-block instead,")
+        print("       or `/work-plan orient --pick` for the interactive track picker.")
+        return 1
+
+    branch = _git(["rev-parse", "--abbrev-ref", "HEAD"], cwd)
+    upstream, ahead = _ahead_of_upstream(cwd)
+    modified = _modified_files(cwd)
+    commits = _recent_commits(cwd, n=3)
+    now = datetime.now().strftime("%Y-%m-%d %H:%M")
+
+    print(_top_rule("current directory"))
+    print(f"Path:   {cwd}")
+    if upstream:
+        print(f"Branch: {branch}  ({ahead} ahead of {upstream}, {len(modified)} uncommitted)")
+    else:
+        print(f"Branch: {branch}  (no upstream tracked, {len(modified)} uncommitted)")
+
+    if commits:
+        print()
+        print("Last 3 commits:")
+        for sha, msg in commits:
+            print(f"  {sha} {msg}")
+
+    if modified:
+        print()
+        print("Modified:")
+        for entry in modified[:20]:
+            print(f"  {entry}")
+        if len(modified) > 20:
+            print(f"  … and {len(modified) - 20} more")
+
+    print()
+    print(f"Snapshot: {now}")
+    print(_bottom_rule())
+    return 0
+
+
+def _is_closed(state: Optional[str]) -> bool:
+    return (state or "").upper() in ("CLOSED", "MERGED")
+
+
+def _state_suffix(state: Optional[str]) -> str:
+    return "  (closed)" if _is_closed(state) else ""
+
+
+def _milestone_prefix(ms: Optional[str]) -> str:
+    return f"[{ms}] " if ms else ""
+
+
+def _top_rule(slug: str) -> str:
+    label = f" {slug} "
+    left = RULE_CHAR * 3
+    used = len(left) + len(label)
+    right = RULE_CHAR * max(3, RULE_WIDTH - used)
+    return f"{left}{label}{right}"
+
+
+def _bottom_rule() -> str:
+    return RULE_CHAR * RULE_WIDTH
+
+
+def _last_session_summary(body: str) -> tuple[Optional[str], str]:
+    """Return (timestamp, one-line summary) of the most recent session block."""
+    if "### Session — " not in body:
+        return (None, "")
+    idx = body.rfind("### Session — ")
+    rest = body[idx:]
+    end = len(rest)
+    for marker in ("\n### ", "\n## "):
+        m = rest.find(marker, 1)
+        if m != -1 and m < end:
+            end = m
+    block = rest[:end]
+
+    lines = block.split("\n")
+    header = lines[0]
+    ts_match = re.match(r"### Session — (.+?)\s*$", header)
+    ts = ts_match.group(1).strip() if ts_match else None
+
+    summary = ""
+    for line in lines[1:]:
+        s = line.strip()
+        if not s:
+            continue
+        if s.startswith("- "):
+            s = s[2:].strip()
+        summary = s
+        break
+    return (ts, summary)
+
+
+def _new_issues_since_handoff(track, last_handoff_iso: Optional[str],
+                              slug: str, listed_nums: list[int]) -> list[dict]:
+    if not (track.repo and last_handoff_iso):
+        return []
+    try:
+        last_dt = parse_iso_timestamp(last_handoff_iso)
+    except ValueError:
+        return []
+    days = max(1, int((datetime.now() - last_dt).total_seconds() / 86400))
+    slug_labels = build_slug_labels([track])
+    new_map = find_new_issues_for_tracks(track.repo, [slug], slug_labels=slug_labels, since_days=days)
+    listed = set(listed_nums)
+    return [i for i in new_map.get(slug, []) if i["number"] not in listed]
+
+
+# === Helpers for cwd-snapshot mode ===
+
+def _is_git_repo(cwd: Path) -> bool:
+    proc = subprocess.run(
+        ["git", "rev-parse", "--is-inside-work-tree"],
+        cwd=str(cwd), capture_output=True, text=True,
+    )
+    return proc.returncode == 0 and proc.stdout.strip() == "true"
+
+
+def _git(args: list[str], cwd: Path) -> str:
+    proc = subprocess.run(
+        ["git", *args], cwd=str(cwd), capture_output=True, text=True,
+    )
+    return proc.stdout.strip() if proc.returncode == 0 else ""
+
+
+def _ahead_of_upstream(cwd: Path) -> tuple[str, int]:
+    upstream = _git(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"], cwd)
+    if not upstream:
+        return ("", 0)
+    ahead_str = _git(["rev-list", "--count", f"{upstream}..HEAD"], cwd)
+    try:
+        return (upstream, int(ahead_str or "0"))
+    except ValueError:
+        return (upstream, 0)
+
+
+def _modified_files(cwd: Path) -> list[str]:
+    out = _git(["status", "--porcelain"], cwd)
+    if not out:
+        return []
+    return [line for line in out.split("\n") if line.strip()]
+
+
+def _recent_commits(cwd: Path, n: int = 3) -> list[tuple[str, str]]:
+    out = _git(["log", f"-{n}", "--pretty=format:%h %s"], cwd)
+    if not out:
+        return []
+    pairs = []
+    for line in out.split("\n"):
+        if " " in line:
+            sha, msg = line.split(" ", 1)
+            pairs.append((sha, msg))
+    return pairs

package/skills/work-plan/lib/closure.py

@@ -0,0 +1,72 @@
+"""Closure-ready signal detection."""
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Optional
+
+from lib.git_state import last_commit_date, branch_exists
+
+
+@dataclass
+class ClosureSignals:
+    """The 5 closure signals from the spec."""
+    all_issues_closed: bool
+    all_branches_done: bool
+    next_up_empty: bool
+    cold_14d: bool
+    no_recent_related_issues: bool
+
+
+def is_closure_ready(signals: ClosureSignals) -> tuple[bool, list[str]]:
+    """All signals must be true. Returns (ready, blocking-reasons)."""
+    reasons = []
+    if not signals.all_issues_closed:
+        reasons.append("open issues remain")
+    if not signals.all_branches_done:
+        reasons.append("branches still active")
+    if not signals.next_up_empty:
+        reasons.append("next_up is not empty")
+    if not signals.cold_14d:
+        reasons.append("recent commits within 14 days")
+    if not signals.no_recent_related_issues:
+        reasons.append("new related issues in last 30 days")
+    return (not reasons, reasons)
+
+
+def compute_signals(track_meta: dict, github_issues: list[dict],
+                    repo_path: Optional[Path],
+                    recent_related_count: int) -> ClosureSignals:
+    """Build ClosureSignals from observed state."""
+    listed_issue_nums = track_meta.get("github", {}).get("issues") or []
+    state_by_num = {i["number"]: i.get("state", "OPEN") for i in github_issues}
+
+    all_closed = bool(listed_issue_nums) and all(
+        state_by_num.get(n, "OPEN") == "CLOSED" for n in listed_issue_nums
+    )
+
+    branches = track_meta.get("github", {}).get("branches") or []
+    if repo_path:
+        all_branches_done = all(not branch_exists(b, repo_path) for b in branches)
+    else:
+        all_branches_done = len(branches) == 0
+
+    next_up_empty = not (track_meta.get("next_up") or [])
+
+    cutoff = datetime.now() - timedelta(days=14)
+    cold = True
+    if repo_path:
+        for b in branches:
+            last = last_commit_date(b, repo_path)
+            if last and last > cutoff:
+                cold = False
+                break
+
+    no_recent = recent_related_count == 0
+
+    return ClosureSignals(
+        all_issues_closed=all_closed,
+        all_branches_done=all_branches_done,
+        next_up_empty=next_up_empty,
+        cold_14d=cold,
+        no_recent_related_issues=no_recent,
+    )

package/skills/work-plan/lib/config.py

@@ -0,0 +1,88 @@
+"""Load + validate ~/.claude/work-plan/config.yml."""
+import json
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+DEFAULT_CONFIG_PATH = Path.home() / ".claude" / "work-plan" / "config.yml"
+DEFAULT_NOTES_ROOT = Path.home() / ".claude" / "work-plan" / "notes"
+
+_SEED_TEMPLATE = (
+    "# work-plan config — auto-seeded on first run. Edit to customize.\n"
+    "# Run /work-plan init-repo <key> --github=<org/repo> to populate repos:.\n"
+    "notes_root: {notes_root}\n"
+    "repos: {{}}\n"
+)
+
+
+class ConfigError(Exception):
+    pass
+
+
+def ensure_config(path: Path = DEFAULT_CONFIG_PATH,
+                  notes_root: Path = DEFAULT_NOTES_ROOT) -> bool:
+    """Create a default config.yml (and notes_root dir) if absent.
+
+    Single source of the seed content — install.sh/install.ps1 delegate here, so
+    plugin installs (which run no install hook) and script installs behave
+    identically. `notes_root` is written as an ABSOLUTE path (never a literal
+    `~`, which downstream `Path(...)` would not expand). Returns True if it
+    created the file, False if it already existed.
+    """
+    path = Path(path)
+    if path.exists():
+        return False
+    notes_root = Path(notes_root).expanduser()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    notes_root.mkdir(parents=True, exist_ok=True)
+    path.write_text(_SEED_TEMPLATE.format(notes_root=notes_root), encoding="utf-8")
+    return True
+
+
+def load_config(path: Path = DEFAULT_CONFIG_PATH,
+                notes_root: Path = DEFAULT_NOTES_ROOT) -> dict:
+    """Load and validate. Self-seeds a default config if absent (no install hook
+    exists for plugin installs). Normalizes string-shape repo entries to dicts."""
+    path = Path(path)
+    if not path.exists():
+        ensure_config(path, notes_root)
+    text = path.read_text(encoding="utf-8")
+    proc = subprocess.run(
+        ["yq", "-o=json", "."], input=text,
+        capture_output=True, text=True, check=True,
+    )
+    cfg = json.loads(proc.stdout)
+    if not isinstance(cfg, dict):
+        raise ConfigError(f"config.yml must be a YAML mapping; got {type(cfg).__name__}")
+    if "notes_root" not in cfg:
+        raise ConfigError("config.yml missing required key 'notes_root'.")
+    cfg.setdefault("repos", {})
+    # Normalize string-shape entries to dict shape
+    for folder, val in list(cfg["repos"].items()):
+        if isinstance(val, str):
+            cfg["repos"][folder] = {"github": val, "local": None}
+        elif isinstance(val, dict):
+            val.setdefault("local", None)
+            if "github" not in val:
+                raise ConfigError(f"repo '{folder}' missing 'github' key")
+        else:
+            raise ConfigError(f"repo '{folder}' must be string or dict, got {type(val).__name__}")
+    return cfg
+
+
+def is_valid_git_repo(path: Path) -> bool:
+    """Return True if path is a directory that contains a .git entry."""
+    p = Path(path)
+    return p.is_dir() and (p / ".git").exists()
+
+
+def resolve_github_for_folder(folder_name: str, cfg: dict) -> Optional[str]:
+    entry = cfg.get("repos", {}).get(folder_name)
+    return entry.get("github") if entry else None
+
+
+def resolve_local_path_for_folder(folder_name: str, cfg: dict) -> Optional[Path]:
+    entry = cfg.get("repos", {}).get(folder_name)
+    if not entry or not entry.get("local"):
+        return None
+    return Path(entry["local"]).expanduser()

package/skills/work-plan/lib/doc_discovery.py

@@ -0,0 +1,41 @@
+"""Discover plan/spec docs in a repo via configurable globs, and classify each."""
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+DEFAULT_GLOBS = [
+    "docs/superpowers/plans/*.md",
+    "docs/superpowers/specs/*.md",
+    "docs/plans/*.md",
+]
+
+
+@dataclass
+class Doc:
+    path: Path   # absolute
+    rel: str     # repo-relative POSIX-style
+    kind: str    # "plan" | "spec" | "adhoc"
+
+
+def classify_kind(rel: str) -> str:
+    """Heuristic doc-kind from its repo-relative path."""
+    if rel.endswith("-design.md") or "/specs/" in rel:
+        return "spec"
+    if "/plans/" in rel:
+        return "plan"
+    return "adhoc"
+
+
+def discover_docs(repo_root: Path, globs: Optional[list] = None) -> list:
+    globs = globs or DEFAULT_GLOBS
+    repo_root = Path(repo_root)
+    out = []
+    seen = set()
+    for g in globs:
+        for p in sorted(repo_root.glob(g)):
+            if not p.is_file() or p in seen:
+                continue
+            seen.add(p)
+            rel = p.relative_to(repo_root).as_posix()
+            out.append(Doc(path=p, rel=rel, kind=classify_kind(rel)))
+    return out

package/skills/work-plan/lib/drift.py

@@ -0,0 +1,32 @@
+"""Detect drift between body status table and GitHub state."""
+from lib.status_table import find_status_table, ISSUE_NUM_RE
+
+
+def detect_drift(body: str, github_issues: list[dict]) -> list[dict]:
+    """Return list of {issue, body_status, github_state} for drifted rows."""
+    table = find_status_table(body)
+    if not table:
+        return []
+
+    state_by_num = {i["number"]: i.get("state", "OPEN") for i in github_issues}
+    drift = []
+    sidx = table["status_col_index"]
+    for row in table["rows"]:
+        nums = []
+        for cell in row["cells"]:
+            nums.extend(int(m) for m in ISSUE_NUM_RE.findall(cell))
+        if not nums:
+            continue
+        body_status = row["cells"][sidx].strip().lower() if sidx < len(row["cells"]) else ""
+        for num in nums:
+            if num not in state_by_num:
+                continue
+            gh_state = state_by_num[num]
+            looks_closed = any(k in body_status for k in ("✅", "shipped", "merged", "closed"))
+            looks_open = "🔲" in body_status or "open" in body_status
+
+            if gh_state == "CLOSED" and not looks_closed:
+                drift.append({"issue": num, "body_status": body_status, "github_state": "CLOSED"})
+            elif gh_state == "OPEN" and looks_closed:
+                drift.append({"issue": num, "body_status": body_status, "github_state": "OPEN"})
+    return drift

package/skills/work-plan/lib/export_model.py

@@ -0,0 +1,42 @@
+"""Build the versioned viewer export structure from tracks + fetched issues."""
+from lib.github_state import format_assignees, short_milestone
+
+SCHEMA = 1
+
+def _issue(i: dict) -> dict:
+    state = (i.get("state") or "OPEN").lower()
+    return {
+        "number": i.get("number"),
+        "title": i.get("title", ""),
+        "state": "closed" if state in ("closed", "merged") else "open",
+        "assignee": (format_assignees(i) if i.get("assignees") else "—"),
+        "milestone": short_milestone(i.get("milestone")) or None,
+    }
+
+def build_export(tracks, issues_by_track, visibility, now: str,
+                 untracked_by_repo=None) -> dict:
+    out = {"schema": SCHEMA, "generated_at": now, "tracks": []}
+    for t in tracks:
+        issues = [_issue(i) for i in issues_by_track.get(t.name, [])]
+        opened = sum(1 for i in issues if i["state"] == "open")
+        closed_nums = {i["number"] for i in issues if i["state"] == "closed"}
+        next_up = [n for n in (t.meta.get("next_up") or []) if n not in closed_nums]
+        out["tracks"].append({
+            "name": t.name,
+            "repo": t.repo,
+            "tier": getattr(t, "tier", "private") or "private",
+            "status": t.meta.get("status"),
+            "launch_priority": t.meta.get("launch_priority"),
+            "milestone_alignment": t.meta.get("milestone_alignment"),
+            "visibility": visibility.get(t.repo),
+            "blockers": list(t.meta.get("blockers") or []),
+            "next_up": next_up,
+            "rollup": {"open": opened, "closed": len(issues) - opened},
+            "issues": issues,
+        })
+    out["untracked"] = [
+        {"repo": repo, "issues": [_issue(r) for r in rows]}
+        for repo, rows in (untracked_by_repo or {}).items()
+        if rows
+    ]
+    return out

package/skills/work-plan/lib/frontmatter.py

@@ -0,0 +1,48 @@
+"""Parse + write YAML frontmatter on markdown files. Body-preserving."""
+import json
+import re
+import subprocess
+from pathlib import Path
+from typing import Tuple
+
+# Use [ \t]* (not \s*) so horizontal-only whitespace is consumed after ---,
+# preserving any leading newline that is part of the body.
+FRONTMATTER_RE = re.compile(r"^---[ \t]*\n(.*?)\n---[ \t]*\n(.*)$", re.DOTALL)
+
+
+def parse_file(path: Path) -> Tuple[dict, str]:
+    """Parse markdown with optional YAML frontmatter. Returns (meta, body)."""
+    text = Path(path).read_text(encoding="utf-8")
+    match = FRONTMATTER_RE.match(text)
+    if not match:
+        return ({}, text)
+    meta = _yaml_to_dict(match.group(1))
+    return (meta, match.group(2))
+
+
+def write_file(path: Path, meta: dict, body: str) -> None:
+    """Write markdown with frontmatter. Empty meta = body only."""
+    if not meta:
+        Path(path).write_text(body, encoding="utf-8")
+        return
+    yaml_text = _dict_to_yaml(meta)
+    Path(path).write_text(f"---\n{yaml_text}---\n{body}", encoding="utf-8")
+
+
+def _yaml_to_dict(yaml_text: str) -> dict:
+    proc = subprocess.run(
+        ["yq", "-o=json", "."], input=yaml_text,
+        capture_output=True, text=True, check=True,
+    )
+    return json.loads(proc.stdout)
+
+
+def _dict_to_yaml(d: dict) -> str:
+    proc = subprocess.run(
+        ["yq", "-P", "."], input=json.dumps(d),
+        capture_output=True, text=True, check=True,
+    )
+    out = proc.stdout
+    if not out.endswith("\n"):
+        out += "\n"
+    return out