@stylusnexus/work-plan 2026.6.9

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

@@ -0,0 +1,53 @@
+"""set-notes-root subcommand — non-interactively relocate notes_root in config.
+
+Called by the VS Code viewer's cold-start onboarding when the user picks a
+folder. Config writes stay in the CLI (the engine), not the extension.
+
+Usage: set-notes-root <path>
+"""
+import subprocess
+from pathlib import Path
+
+from lib.config import load_config, DEFAULT_CONFIG_PATH
+from lib.prompts import parse_flags
+from lib.tracks import discover_tracks
+
+
+def run(args: list[str]) -> int:
+    _, positional = parse_flags(args, set())
+
+    if not positional:
+        print("usage: work_plan.py set-notes-root <path>")
+        return 2
+
+    new_root = Path(positional[0]).expanduser().resolve()
+
+    cfg = load_config()
+    current_root = Path(cfg["notes_root"]).expanduser().resolve()
+
+    # Orphan warning (informational only — no moves, no prompt)
+    if new_root != current_root:
+        tracks = discover_tracks(cfg)
+        if tracks:
+            print(
+                f"WARN: {len(tracks)} track(s) exist under {current_root}. "
+                "They will NOT be moved — move them manually to the new location "
+                "before using the viewer, or they won't appear."
+            )
+
+    # Ensure the target directory exists
+    new_root.mkdir(parents=True, exist_ok=True)
+
+    # Write the new notes_root into config via yq (mikefarah/yq)
+    yq_expr = f'.notes_root = "{new_root}"'
+    try:
+        subprocess.run(
+            ["yq", "-i", yq_expr, str(DEFAULT_CONFIG_PATH)],
+            check=True, capture_output=True, text=True,
+        )
+    except subprocess.CalledProcessError as e:
+        print(f"ERROR: yq failed to update config: {e.stderr}")
+        return 1
+
+    print(f"✓ notes_root set to {new_root}")
+    return 0

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

@@ -0,0 +1,139 @@
+"""slot subcommand."""
+import json
+import subprocess
+
+from lib.config import load_config, ConfigError
+from lib.tracks import discover_tracks, find_track_by_name
+from lib.frontmatter import write_file
+from lib.write_guard import needs_confirm, make_token, valid_token
+from lib.prompts import parse_flags, prompt_input
+
+
+def _find_prior_owners(issue_num: int, repo: str, target_name: str, tracks):
+    """Active tracks in `repo` (excluding `target_name`) whose frontmatter
+    already lists `issue_num`. Lets slot offer a move when GitHub labels
+    moved an issue across tracks but the old frontmatter still claims it."""
+    owners = []
+    for t in tracks:
+        if not t.has_frontmatter or t.name == target_name or t.repo != repo:
+            continue
+        if t.meta.get("status") not in ("active", "in-progress", "blocked"):
+            continue
+        if issue_num in (t.meta.get("github", {}).get("issues") or []):
+            owners.append(t)
+    return owners
+
+
+def run(args: list[str]) -> int:
+    # --confirm uses equals form: --confirm=<token>
+    # --move / --no-move are bare flags
+    flags, positional = parse_flags(args, {"--confirm", "--move", "--no-move"})
+    if not positional:
+        print("usage: work_plan.py slot <issue-num> [track-name]")
+        return 2
+    try:
+        issue_num = int(positional[0])
+    except ValueError:
+        print(f"ERROR: '{positional[0]}' is not an issue number.")
+        return 2
+    target_name = positional[1] if len(positional) > 1 else None
+
+    if "--move" in flags and "--no-move" in flags:
+        print("ERROR: --move and --no-move are mutually exclusive.")
+        return 2
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+
+    tracks = discover_tracks(cfg)
+    active = [t for t in tracks if t.has_frontmatter
+              and t.meta.get("status") in ("active", "in-progress", "blocked")]
+
+    if target_name:
+        target = find_track_by_name(target_name, tracks, active_only=True)
+        if not target:
+            print(f"No active track matching '{target_name}'.")
+            return 1
+    else:
+        print("Active tracks:")
+        for i, t in enumerate(active, 1):
+            print(f"  [{i}] {t.name} ({t.meta.get('launch_priority','P3')}, "
+                  f"{t.meta.get('milestone_alignment','—')})")
+        choice = prompt_input("\nSlot into which? (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
+            target = active[idx]
+        else:
+            matching = [t for t in active if t.name == choice or t.meta.get("track") == choice]
+            if not matching:
+                print(f"No active track matching '{choice}'.")
+                return 1
+            target = matching[0]
+
+    issues = list(target.meta.get("github", {}).get("issues") or [])
+    if issue_num in issues:
+        print(f"#{issue_num} already in track '{target.name}'.")
+        return 0
+
+    # Public-repo confirm gate (the extension surfaces this as a modal).
+    # Placed after target resolution and the "already in track" no-op so we
+    # don't gate a no-op write.
+    confirm = flags.get("--confirm")
+    if target.repo and needs_confirm(target.repo, cfg) and not (
+        isinstance(confirm, str) and valid_token(confirm, target.repo, target.name)
+    ):
+        print(json.dumps({
+            "needs_confirm": True,
+            "reason": (
+                f"{target.repo} is PUBLIC (or visibility unknown); "
+                f"slotting #{issue_num} will be written there."
+            ),
+            "token": make_token(target.repo, target.name),
+        }))
+        return 0
+
+    # Determine move behavior from flags.
+    # --move: remove issue from prior owners.
+    # Default / --no-move: add-only; print a note naming prior owners.
+    do_move = "--move" in flags
+
+    sources = _find_prior_owners(issue_num, target.repo, target.name, tracks)
+
+    issues.append(issue_num)
+    target.meta.setdefault("github", {})["issues"] = sorted(issues)
+
+    proc = subprocess.run(
+        ["gh", "issue", "view", str(issue_num),
+         "--repo", target.repo, "--json", "milestone"],
+        capture_output=True, text=True,
+    )
+    if proc.returncode == 0:
+        info = json.loads(proc.stdout)
+        m = info.get("milestone", {})
+        if m and m.get("title") and m["title"] != target.meta.get("milestone_alignment"):
+            print(f"⚠  #{issue_num} is on milestone '{m['title']}', "
+                  f"track '{target.name}' aligned to '{target.meta.get('milestone_alignment')}'.")
+
+    if sources and do_move:
+        for src in sources:
+            src_issues = [n for n in (src.meta.get("github", {}).get("issues") or [])
+                          if n != issue_num]
+            src.meta.setdefault("github", {})["issues"] = src_issues
+            write_file(src.path, src.meta, src.body)
+            print(f"  ✓ Removed #{issue_num} from '{src.name}'.")
+    elif sources and not do_move:
+        names = ", ".join(f"'{t.name}'" for t in sources)
+        print(f"ℹ #{issue_num} still listed in {names} — re-run with --move to relocate.")
+
+    write_file(target.path, target.meta, target.body)
+    print(f"✓ Slotted #{issue_num} into '{target.name}'.")
+    return 0

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

@@ -0,0 +1,132 @@
+"""suggest-priorities subcommand: prepare batch for AI labeling.
+
+Two-step:
+1. CLI fetches all unlabeled open issues, writes JSON batch + prints prompt
+2. Agent fills priorities into ~/.claude/work-plan/cache/priorities.answers.json
+3. Run with --apply to apply via gh
+"""
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+from lib.config import load_config, ConfigError
+from lib.scratch import cache_dir
+
+
+def _batch_path() -> Path:
+    return cache_dir() / "priorities.json"
+PROMPT_TEMPLATE = """\
+For each GitHub issue below, suggest a priority label (P0/P1/P2/P3) based on
+title, milestone, and labels. Return JSON: [{"number": N, "priority": "P0"}, ...]
+
+Heuristics:
+- P0: launch-critical bugs/features tagged for v0.4.0 or v1.0.0 with urgent verbs (blocks, breaks, must)
+- P1: important but not blocking; v0.4.0/v1.0.0 features
+- P2: should ship eventually; v1.0.0 nice-to-haves, v2.0.0 features
+- P3: backlog; long-tail polish, parked work
+
+Skip issues with insufficient signal. Output ONLY valid JSON.
+
+Issues:
+"""
+
+
+def run(args: list[str]) -> int:
+    apply_mode = "--apply" in args
+    repo_arg = next((a for a in args if a.startswith("--repo=")), None)
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+
+    if apply_mode:
+        return _apply(cfg)
+
+    repos = list(cfg["repos"].keys())
+    if repo_arg:
+        repo_folder = repo_arg.split("=", 1)[1]
+        repos = [repo_folder]
+    elif len(repos) > 1:
+        print("Multiple repos in config. Specify with --repo=<folder-name>.")
+        return 1
+
+    folder = repos[0]
+    repo = cfg["repos"][folder]["github"]
+    print(f"Fetching unlabeled issues in {repo}...")
+
+    proc = subprocess.run(
+        ["gh", "issue", "list", "--repo", repo,
+         "--state", "open", "--limit", "100",
+         "--json", "number,title,milestone,labels,url"],
+        capture_output=True, text=True,
+    )
+    if proc.returncode != 0:
+        print(f"ERROR fetching issues: {proc.stderr}")
+        return 1
+    all_issues = json.loads(proc.stdout) if proc.stdout.strip() else []
+
+    unlabeled = [
+        i for i in all_issues
+        if not any(l["name"].startswith("priority/") for l in i.get("labels", []))
+    ]
+    if not unlabeled:
+        print("All open issues already have priority labels.")
+        return 0
+
+    batch_path = _batch_path()
+    batch_path.write_text(json.dumps({"repo": repo, "issues": unlabeled}, indent=2))
+    print(f"Wrote {len(unlabeled)} issues to {batch_path}")
+    print()
+    print("=" * 60)
+    print(PROMPT_TEMPLATE)
+    for i in unlabeled:
+        m = i.get("milestone", {})
+        m_title = m.get("title", "—") if m else "—"
+        labels = [l["name"] for l in i.get("labels", [])]
+        print(f"#{i['number']} [{m_title}] [{','.join(labels) or 'no-labels'}] {i['title']}")
+    print("=" * 60)
+    print()
+    print(f"After agent returns JSON, save to {batch_path.with_suffix('.answers.json')}")
+    print(f"Then run: python3 ~/.claude/skills/work-plan/work_plan.py suggest-priorities --apply")
+    return 0
+
+
+def _apply(cfg: dict) -> int:
+    batch_path = _batch_path()
+    answers_path = batch_path.with_suffix(".answers.json")
+    if not answers_path.exists():
+        print(f"ERROR: {answers_path} not found. Run without --apply first.")
+        return 1
+    if not batch_path.exists():
+        print(f"ERROR: {batch_path} not found.")
+        return 1
+    batch = json.loads(batch_path.read_text())
+    repo = batch["repo"]
+    allowed_repos = {entry.get("github") for entry in cfg.get("repos", {}).values()}
+    if repo not in allowed_repos:
+        print(f"ERROR: batch repo '{repo}' not in config.yml repos.")
+        return 1
+    answers = json.loads(answers_path.read_text())
+
+    print(f"Applying {len(answers)} priority labels to {repo}...")
+    for ans in answers:
+        num = ans["number"]
+        priority = ans["priority"]
+        if priority not in ("P0", "P1", "P2", "P3"):
+            print(f"  SKIP #{num}: invalid priority '{priority}'")
+            continue
+        proc = subprocess.run(
+            ["gh", "issue", "edit", str(num),
+             "--repo", repo,
+             "--add-label", f"priority/{priority}"],
+            capture_output=True, text=True,
+        )
+        if proc.returncode == 0:
+            print(f"  ✓ #{num} → priority/{priority}")
+        else:
+            print(f"  ✗ #{num}: {proc.stderr.strip()}")
+    print("Done.")
+    return 0

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