@stylusnexus/work-plan 2026.6.9

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

@@ -0,0 +1,104 @@
+"""hygiene subcommand: weekly cleanup wrapper.
+
+Runs in sequence:
+  1. refresh-md --all --yes  (drift in body status tables)
+  2. reconcile --all          (sync track/<slug> labels ↔ frontmatter)
+  3. duplicates               (find consolidation candidates)
+
+One command for the standard weekly maintenance pass.
+
+Pass --repo=<key> to scope steps 1 and 2 to a single repo. Step 3 (duplicates)
+is per-repo, so:
+  - when --repo is set, it's scoped to that repo;
+  - when --repo is absent and config has exactly one repo, it runs against
+    that repo;
+  - when --repo is absent and config has multiple repos, it's skipped cleanly
+    (rather than letting duplicates exit non-zero on the ambiguous case).
+"""
+from commands import refresh_md, reconcile, duplicates
+from lib.config import load_config, ConfigError
+from lib.prompts import parse_flags
+
+
+def _resolve_repo_folder(repo_key: str, cfg: dict):
+    """Translate hygiene's --repo arg (folder key OR org/repo slug) to a config
+    folder key, which is what duplicates expects. Returns None if unresolvable.
+    """
+    repos = cfg.get("repos", {})
+    if repo_key in repos:
+        return repo_key
+    k = repo_key.lower()
+    for folder, entry in repos.items():
+        if entry.get("github", "").lower() == k:
+            return folder
+    return None
+
+
+def run(args: list[str]) -> int:
+    flags, _ = parse_flags(args, {"--yes", "--no-duplicates", "--repo"})
+    skip_dups = flags.get("--no-duplicates", False)
+    yes = flags.get("--yes", False)
+    repo_key = flags.get("--repo")
+    if repo_key is True:
+        print("usage: work_plan.py hygiene [--yes] [--no-duplicates] [--repo=<key>]")
+        return 2
+
+    scope_label = f" --repo={repo_key}" if repo_key else " --all"
+
+    print("=" * 60)
+    print(f"WEEKLY HYGIENE — step 1 of 3: refresh-md{scope_label}")
+    print("=" * 60)
+    refresh_args = [f"--repo={repo_key}"] if repo_key else ["--all"]
+    if yes:
+        refresh_args.append("--yes")
+    rc = refresh_md.run(refresh_args)
+    if rc != 0:
+        print(f"\n⚠ refresh-md exited with code {rc}; continuing.")
+
+    print()
+    print("=" * 60)
+    print(f"WEEKLY HYGIENE — step 2 of 3: reconcile{scope_label}")
+    print("=" * 60)
+    reconcile_args = [f"--repo={repo_key}"] if repo_key else ["--all"]
+    rc = reconcile.run(reconcile_args)
+    if rc != 0:
+        print(f"\n⚠ reconcile exited with code {rc}; continuing.")
+
+    if skip_dups:
+        print()
+        print("(skipping duplicates per --no-duplicates)")
+        return 0
+
+    print()
+    print("=" * 60)
+    print("WEEKLY HYGIENE — step 3 of 3: duplicates")
+    print("=" * 60)
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"⚠ could not load config for duplicates step: {e}")
+        return 0
+
+    dupes_args: list[str] = []
+    repos = cfg.get("repos", {})
+    if repo_key:
+        folder = _resolve_repo_folder(repo_key, cfg)
+        if folder is None:
+            print(f"(skipping duplicates: --repo={repo_key} not found in config.yml)")
+            return 0
+        dupes_args = [f"--repo={folder}"]
+    elif len(repos) > 1:
+        print("(skipping duplicates: multiple repos in config and no --repo passed.")
+        print(" run `/work-plan duplicates --repo=<folder-name>` per repo to scan them.)")
+        return 0
+    # else: 0 or 1 repos → duplicates handles both (errors / single-repo auto-pick)
+
+    rc = duplicates.run(dupes_args)
+    if rc != 0:
+        print(f"\n⚠ duplicates exited with code {rc}.")
+
+    print()
+    print("✓ Weekly hygiene complete. Review the duplicate candidates above and "
+          "consolidate any real dupes via `gh issue close`.")
+    return 0

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

@@ -0,0 +1,96 @@
+"""init subcommand — non-interactive, flag-driven."""
+import json
+import re
+from datetime import datetime
+from pathlib import Path
+
+from lib.config import load_config, ConfigError, resolve_github_for_folder
+from lib.frontmatter import parse_file, write_file
+from lib.prompts import parse_flags
+from lib.write_guard import needs_confirm, make_token, valid_token
+
+_VALID_PRIORITIES = {"P0", "P1", "P2", "P3"}
+
+
+def run(args: list[str]) -> int:
+    flags, positional = parse_flags(args, {"--priority", "--milestone", "--confirm"})
+
+    if not positional:
+        print("usage: work_plan.py init <path-to-md>")
+        return 2
+
+    path = Path(positional[0]).expanduser().resolve()
+    if not path.exists():
+        print(f"ERROR: file not found: {path}")
+        return 1
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+
+    meta, body = parse_file(path)
+    if meta:
+        print(f"{path.name} already has frontmatter.")
+        return 0
+
+    slug = re.sub(r"[^a-z0-9-]+", "-", path.stem.lower()).strip("-")
+
+    notes_root = Path(cfg["notes_root"])
+    try:
+        rel = path.relative_to(notes_root)
+        folder = rel.parts[0] if len(rel.parts) > 1 else None
+    except ValueError:
+        folder = None
+    repo = resolve_github_for_folder(folder, cfg) if folder else None
+
+    issue_nums = sorted(set(int(m) for m in re.findall(r"#(\d+)", body)))
+
+    # Resolve priority — default P2; invalid value falls back to P2
+    raw_priority = flags.get("--priority")
+    if isinstance(raw_priority, str):
+        priority = raw_priority.upper()
+        if priority not in _VALID_PRIORITIES:
+            priority = "P2"
+    else:
+        priority = "P2"
+
+    # Resolve milestone — default v1.0.0
+    milestone_flag = flags.get("--milestone")
+    milestone = milestone_flag if isinstance(milestone_flag, str) else "v1.0.0"
+
+    # Confirm-token gate — only for real resolvable repos (not TBD/unknown).
+    # Checked before printing the info block so the gate output is the only
+    # stdout (the extension surfaces this as a modal, JSON-parse the first line).
+    if repo and repo != "TBD" and needs_confirm(repo, cfg):
+        confirm = flags.get("--confirm")
+        if not (isinstance(confirm, str) and valid_token(confirm, repo, slug)):
+            print(json.dumps({
+                "needs_confirm": True,
+                "reason": (
+                    f"{repo} is PUBLIC (or visibility unknown); "
+                    f"the new track '{slug}' references it."
+                ),
+                "token": make_token(repo, slug),
+            }))
+            return 0
+
+    print(f"Initializing: {path.name}")
+    print(f"  track: {slug}")
+    print(f"  repo: {repo or '(unknown — will set TBD)'}")
+    print(f"  issues found in body: {issue_nums or '(none)'}")
+
+    now = datetime.now().strftime("%Y-%m-%dT%H:%M")
+    meta = {
+        "track": slug, "status": "active",
+        "launch_priority": priority,
+        "milestone_alignment": milestone,
+        "github": {"repo": repo or "TBD", "issues": issue_nums, "branches": []},
+        "related_tracks": [],
+        "last_touched": now, "last_handoff": now,
+        "next_up": [], "blockers": [],
+    }
+    write_file(path, meta, body)
+    print(f"✓ Frontmatter added to {path.name}.")
+    return 0

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

@@ -0,0 +1,90 @@
+"""init-repo subcommand — bootstrap a new repo block + notes folder.
+
+Non-interactive: --github is required; --local is optional (no prompts).
+"""
+import json
+import re
+import subprocess
+from pathlib import Path
+
+from lib.config import load_config, ConfigError, DEFAULT_CONFIG_PATH
+from lib.prompts import parse_flags
+
+
+def run(args: list[str]) -> int:
+    flags, positional = parse_flags(args, {"--github", "--local"})
+    if not positional:
+        print("usage: work_plan.py init-repo <key> --github=<org/repo> [--local=<path>]")
+        return 2
+
+    key = positional[0]
+    if not re.fullmatch(r"[a-z][a-z0-9-]*", key):
+        print(f"ERROR: '{key}' is not a valid key. Use lowercase letters, digits, hyphens; must start with a letter.")
+        return 2
+
+    # --github is required; no prompt fallback
+    github = flags.get("--github")
+    if not github or "/" not in github:
+        if not github:
+            print("ERROR: --github is required (e.g. --github=org/repo).")
+        else:
+            print("ERROR: github slug must be in the form 'org/repo'.")
+        return 2
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        print("\nRun ./install.sh from the toolkit root to seed your config first.")
+        return 1
+
+    if key in cfg.get("repos", {}):
+        print(f"ERROR: repo '{key}' already exists in {DEFAULT_CONFIG_PATH}.")
+        print("Edit it manually, or pick a different key.")
+        return 1
+
+    # --local is optional; if absent, skip (no prompt)
+    local = flags.get("--local") or None
+    if local:
+        local_path = Path(local).expanduser()
+        if not local_path.exists():
+            print(f"WARN: {local_path} does not exist. Saving anyway — fix later if wrong.")
+
+    notes_root = Path(cfg["notes_root"]).expanduser()
+    if not notes_root.exists():
+        print(f"ERROR: notes_root {notes_root} does not exist.")
+        print("Fix the path in ~/.claude/work-plan/config.yml or create the directory.")
+        return 1
+
+    repo_dir = notes_root / key
+    archive_shipped = repo_dir / "archive" / "shipped"
+    archive_abandoned = repo_dir / "archive" / "abandoned"
+    archive_shipped.mkdir(parents=True, exist_ok=True)
+    archive_abandoned.mkdir(parents=True, exist_ok=True)
+    (archive_shipped / ".gitkeep").touch()
+    (archive_abandoned / ".gitkeep").touch()
+    print(f"✓ Created notes folder: {repo_dir}/")
+    print(f"  ├── archive/shipped/")
+    print(f"  └── archive/abandoned/")
+
+    repo_block = {"github": github}
+    if local:
+        repo_block["local"] = local
+
+    yq_expr = f'.repos.{key} = {json.dumps(repo_block)}'
+    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"✓ Added repo '{key}' to {DEFAULT_CONFIG_PATH}")
+
+    print()
+    print("Next steps:")
+    print(f"  • Add a track:        /work-plan init '{repo_dir}/<track-slug>.md'")
+    print(f"  • AI-cluster issues:  /work-plan group --repo={key} --milestone=v1.0.0")
+    print(f"  • See it listed:      /work-plan list")
+    return 0

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

@@ -0,0 +1,39 @@
+"""list subcommand."""
+from lib.config import load_config, ConfigError
+from lib.tracks import discover_tracks, discover_archived_tracks
+
+
+def run(args: list[str]) -> int:
+    show_all = "--all" in args
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+
+    tracks = discover_tracks(cfg)
+    if not tracks and not show_all:
+        print(f"No tracks found under {cfg['notes_root']}")
+        return 0
+
+    print(f"Tracks under {cfg['notes_root']}:\n")
+    for t in tracks:
+        status = t.meta.get("status", "(no frontmatter)")
+        priority = t.meta.get("launch_priority", "—")
+        repo = t.repo or "(no repo)"
+        flags = []
+        if t.needs_init:
+            flags.append("NEEDS INIT")
+        if t.needs_filing:
+            flags.append("NEEDS FILING")
+        flag_str = f" [{', '.join(flags)}]" if flags else ""
+        print(f"  {t.name:30}  {status:14}  {priority:3}  {repo}{flag_str}")
+
+    if show_all:
+        archived = discover_archived_tracks(cfg)
+        if archived:
+            print("\nArchived:")
+            for a in archived:
+                end_state = a.meta.get("status", "?")
+                print(f"  {a.name:30}  {end_state:14}  {a.repo or '(no repo)'}")
+    return 0

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

@@ -0,0 +1,148 @@
+"""new-track subcommand — one-shot non-interactive track creation.
+
+Creates a brand-new <slug>.md under notes_root/<folder>/ with frontmatter
+written from flags. Designed for headless callers (e.g. the VS Code extension)
+that cannot run interactive init + do not know notes_root upfront.
+
+Usage:
+  new-track <repo> <slug> [--priority=P0..P3] [--milestone=<m>]
+                          [--private] [--confirm=<token>]
+"""
+import json
+import re
+from datetime import datetime
+from pathlib import Path
+
+from lib.config import load_config, ConfigError
+from lib.frontmatter import write_file
+from lib.prompts import parse_flags
+from lib.write_guard import needs_confirm, make_token, valid_token
+
+_VALID_PRIORITIES = {"P0", "P1", "P2", "P3"}
+_SLUG_RE = re.compile(r"^[a-z][a-z0-9-]*$")
+
+
+def run(args: list[str]) -> int:
+    flags, positional = parse_flags(
+        args, {"--priority", "--milestone", "--private", "--confirm"}
+    )
+
+    # Require exactly 2 positionals: repo and slug
+    if len(positional) < 2:
+        print(
+            "usage: work_plan.py new-track <repo> <slug>"
+            " [--priority=P0..P3] [--milestone=<m>] [--private] [--confirm=<token>]"
+        )
+        return 2
+
+    repo_arg = positional[0]
+    slug = positional[1]
+
+    # ------------------------------------------------------------------
+    # Resolve repo + folder from the repo argument
+    # ------------------------------------------------------------------
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+
+    if repo_arg in cfg.get("repos", {}):
+        github = cfg["repos"][repo_arg]["github"]
+        folder = repo_arg
+    elif "/" in repo_arg:
+        github = repo_arg
+        folder = repo_arg.rsplit("/", 1)[-1]
+    else:
+        print(
+            f"ERROR: unknown repo '{repo_arg}' — pass a configured key"
+            " or an org/repo slug"
+        )
+        return 1
+
+    # ------------------------------------------------------------------
+    # Validate slug: lowercase letters / digits / hyphens, starts with letter
+    # ------------------------------------------------------------------
+    if not _SLUG_RE.fullmatch(slug):
+        print(
+            f"ERROR: '{slug}' is not a valid slug."
+            " Use lowercase letters, digits, hyphens; must start with a letter."
+        )
+        return 2
+
+    # ------------------------------------------------------------------
+    # Resolve priority (default P2, invalid → P2) and milestone (default v1.0.0)
+    # ------------------------------------------------------------------
+    raw_priority = flags.get("--priority")
+    if isinstance(raw_priority, str):
+        priority = raw_priority.upper()
+        if priority not in _VALID_PRIORITIES:
+            priority = "P2"
+    else:
+        priority = "P2"
+
+    milestone_flag = flags.get("--milestone")
+    milestone = milestone_flag if isinstance(milestone_flag, str) else "v1.0.0"
+
+    # ------------------------------------------------------------------
+    # Resolve target path
+    # ------------------------------------------------------------------
+    notes_root = Path(cfg["notes_root"]).expanduser()
+    if not notes_root.exists():
+        print(f"ERROR: notes_root {notes_root} does not exist.")
+        return 1
+
+    path = notes_root / folder / f"{slug}.md"
+
+    if path.exists():
+        print(f"ERROR: track '{slug}' already exists at {path}")
+        return 2
+
+    # ------------------------------------------------------------------
+    # Confirm-token gate (BEFORE creating anything)
+    # Mirror the exact JSON shape used by init/slot/close/set.
+    # ------------------------------------------------------------------
+    if needs_confirm(github, cfg):
+        confirm = flags.get("--confirm")
+        if not (isinstance(confirm, str) and valid_token(confirm, github, slug)):
+            print(json.dumps({
+                "needs_confirm": True,
+                "reason": (
+                    f"{github} is PUBLIC (or visibility unknown); "
+                    f"the new track '{slug}' will be written there."
+                ),
+                "token": make_token(github, slug),
+            }))
+            return 0
+
+    # ------------------------------------------------------------------
+    # --private flag: accepted for forward-compat but is a no-op today.
+    # Every track is effectively private now; the two-tier shared/private
+    # model is unbuilt. We accept the flag so callers don't error out.
+    # ------------------------------------------------------------------
+    # (no branch on --private beyond parsing it)
+
+    # ------------------------------------------------------------------
+    # Create folder if missing, then write the track file
+    # ------------------------------------------------------------------
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    now = datetime.now().strftime("%Y-%m-%dT%H:%M")
+    meta = {
+        "track": slug,
+        "status": "active",
+        "launch_priority": priority,
+        "milestone_alignment": milestone,
+        "github": {"repo": github, "issues": [], "branches": []},
+        "related_tracks": [],
+        "last_touched": now,
+        "last_handoff": now,
+        "next_up": [],
+        "blockers": [],
+    }
+    body = f"# {slug}\n"
+    write_file(path, meta, body)
+
+    rel = path.relative_to(notes_root)
+    print(f"✓ Created track '{slug}' for {github} at {rel}")
+    return 0