pan-wizard 2.8.1 → 2.9.1

package/scripts/generate-skills-docs.py

@@ -0,0 +1,560 @@
+#!/usr/bin/env python3
+"""
+Generate PAN Wizard skills documentation from source command files.
+
+Reads all shipped skills (commands/pan/*.md) and dev skills (.claude/commands/*.md),
+parses their YAML frontmatter and content, and produces two documents:
+
+  docs/SKILLS-REFERENCE.md  — Organized summary with tables, descriptions, tool matrix
+  docs/SKILLS-FULL-TEXT.md  — Complete unabridged prompt text of every skill
+
+Usage:
+    python scripts/generate-skills-docs.py              # from repo root
+    python scripts/generate-skills-docs.py --dry-run    # preview without writing
+    python scripts/generate-skills-docs.py --full-only  # only generate SKILLS-FULL-TEXT.md
+    python scripts/generate-skills-docs.py --ref-only   # only generate SKILLS-REFERENCE.md
+"""
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SHIPPED_DIR = REPO_ROOT / "commands" / "pan"
+DEV_DIR = REPO_ROOT / ".claude" / "commands"
+PACKAGE_JSON = REPO_ROOT / "package.json"
+OUT_REFERENCE = REPO_ROOT / "docs" / "SKILLS-REFERENCE.md"
+OUT_FULL_TEXT = REPO_ROOT / "docs" / "SKILLS-FULL-TEXT.md"
+
+# Group ordering for the reference doc (shipped skills)
+GROUP_ORDER = [
+    "Getting Started",
+    "Phase Lifecycle",
+    "Phase Management",
+    "Focus",
+    "Milestone",
+    "Milestone Lifecycle",
+    "Session & Progress",
+    "System",
+    "Community",
+]
+
+# Dev skill categorization (filename -> category)
+DEV_CATEGORIES = {
+    "Development Workflow": [
+        "pandev", "execplan", "superplan", "featureAI", "review",
+    ],
+    "Testing & Verification": [
+        "test", "quick", "pantest", "check", "check-platform", "auditai",
+    ],
+    "Documentation & Audit": [
+        "doc-audit", "docs", "sync",
+    ],
+    "Build & Deploy": [
+        "build", "run", "commit",
+    ],
+    "Session Management": [
+        "session-start", "session-end",
+    ],
+}
+
+# All tools that shipped skills can reference
+ALL_TOOLS = [
+    "Read", "Write", "Edit", "Bash", "Grep", "Glob",
+    "Agent", "Task", "TodoWrite", "AskUserQuestion",
+    "SlashCommand", "WebSearch", "WebFetch",
+]
+
+# ---------------------------------------------------------------------------
+# Frontmatter parser
+# ---------------------------------------------------------------------------
+
+def parse_frontmatter(content: str) -> tuple[dict, str]:
+    """Parse YAML frontmatter from markdown content.
+
+    Returns (metadata_dict, body_after_frontmatter).
+    If no frontmatter found, returns (empty dict, full content).
+    """
+    if not content.startswith("---"):
+        return {}, content
+
+    end = content.find("---", 3)
+    if end == -1:
+        return {}, content
+
+    raw = content[3:end].strip()
+    body = content[end + 3:].strip()
+    meta = {}
+
+    current_key = None
+    current_list = None
+
+    for line in raw.split("\n"):
+        stripped = line.strip()
+        if not stripped:
+            continue
+
+        # List item under a key
+        if stripped.startswith("- ") and current_key:
+            if current_list is None:
+                current_list = []
+            current_list.append(stripped[2:].strip())
+            meta[current_key] = current_list
+            continue
+
+        # Key: value pair
+        if ":" in stripped:
+            # Save previous list if any
+            if current_list is not None:
+                current_list = None
+
+            colon_idx = stripped.index(":")
+            key = stripped[:colon_idx].strip()
+            value = stripped[colon_idx + 1:].strip()
+
+            current_key = key
+
+            if value:
+                # Strip quotes
+                if value.startswith('"') and value.endswith('"'):
+                    value = value[1:-1]
+                elif value.startswith("'") and value.endswith("'"):
+                    value = value[1:-1]
+                meta[key] = value
+                current_list = None
+            else:
+                # Value might be a list on following lines
+                current_list = []
+                meta[key] = current_list
+
+    return meta, body
+
+
+def extract_first_heading(body: str) -> str:
+    """Extract the first # heading from the body."""
+    for line in body.split("\n"):
+        line = line.strip()
+        if line.startswith("# "):
+            return line[2:].strip()
+    return ""
+
+
+# ---------------------------------------------------------------------------
+# Skill loading
+# ---------------------------------------------------------------------------
+
+class Skill:
+    def __init__(self, filepath: Path, is_dev: bool = False):
+        self.filepath = filepath
+        self.is_dev = is_dev
+        self.filename = filepath.stem  # e.g., "focus-auto"
+        self.content = filepath.read_text(encoding="utf-8")
+        self.line_count = self.content.count("\n") + (1 if not self.content.endswith("\n") else 0)
+        self.meta, self.body = parse_frontmatter(self.content)
+
+        # Derive fields
+        if is_dev:
+            self.name = self.meta.get("name", f"/{self.filename}")
+            self.command = f"/{self.filename}"
+        else:
+            raw_name = self.meta.get("name", f"pan:{self.filename}")
+            # Normalize to /pan: prefix
+            if not raw_name.startswith("pan:") and not raw_name.startswith("/pan:"):
+                self.name = f"/pan:{raw_name}"
+            elif raw_name.startswith("pan:"):
+                self.name = f"/{raw_name}"
+            else:
+                self.name = raw_name
+            self.command = self.name
+
+        self.group = self.meta.get("group", "System")
+        self.description = self.meta.get("description", "")
+        raw_tools = self.meta.get("allowed-tools", [])
+        if isinstance(raw_tools, str):
+            # Handle comma-separated format: "Read, Write, Edit"
+            self.tools = [t.strip() for t in raw_tools.split(",") if t.strip()]
+        elif isinstance(raw_tools, list):
+            self.tools = raw_tools
+        else:
+            self.tools = []
+        self.argument_hint = self.meta.get("argument-hint", "")
+        self.heading = extract_first_heading(self.body)
+
+
+def load_shipped_skills() -> list[Skill]:
+    """Load all shipped skills from commands/pan/."""
+    if not SHIPPED_DIR.exists():
+        print(f"Warning: {SHIPPED_DIR} not found", file=sys.stderr)
+        return []
+    skills = []
+    for f in sorted(SHIPPED_DIR.glob("*.md")):
+        skills.append(Skill(f, is_dev=False))
+    return skills
+
+
+def load_dev_skills() -> list[Skill]:
+    """Load all dev skills from .claude/commands/."""
+    if not DEV_DIR.exists():
+        print(f"Warning: {DEV_DIR} not found", file=sys.stderr)
+        return []
+    skills = []
+    for f in sorted(DEV_DIR.glob("*.md")):
+        skills.append(Skill(f, is_dev=True))
+    return skills
+
+
+def get_version() -> str:
+    """Read version from package.json."""
+    try:
+        with open(PACKAGE_JSON, encoding="utf-8") as f:
+            return json.load(f)["version"]
+    except (FileNotFoundError, KeyError):
+        return "unknown"
+
+
+# ---------------------------------------------------------------------------
+# SKILLS-FULL-TEXT.md generator
+# ---------------------------------------------------------------------------
+
+def generate_full_text(shipped: list[Skill], dev: list[Skill], version: str) -> str:
+    """Generate the complete full-text document."""
+    lines = []
+    w = lines.append
+
+    w("# PAN Wizard — Complete Skills Full Text")
+    w("")
+    w("Every skill (slash command) available in PAN Wizard, reproduced in full.")
+    w("This is the actual prompt text that Claude receives when a skill is invoked.")
+    w("")
+    w(f"**Version:** {version} | **Shipped:** {len(shipped)} skills | **Dev:** {len(dev)} skills | **Total:** {len(shipped) + len(dev)}")
+    w("")
+    w("> Auto-generated by `scripts/generate-skills-docs.py` — do not edit manually.")
+    w("")
+    w("---")
+    w("")
+    w(f"## Part 1: Shipped Skills ({len(shipped)})")
+    w("")
+    w("These are installed into host projects via the PAN installer.")
+
+    for skill in shipped:
+        w("")
+        w("---")
+        w("")
+        w(f"### {skill.command} ({skill.line_count} lines)")
+        w("")
+        w("```markdown")
+        w(skill.content.rstrip())
+        w("```")
+        w("")
+
+    w("")
+    w("---")
+    w("")
+    w(f"## Part 2: Dev Skills ({len(dev)})")
+    w("")
+    w("These exist only in the PAN source repository and are NOT shipped to end users.")
+
+    for skill in dev:
+        w("")
+        w("---")
+        w("")
+        w(f"### {skill.command} ({skill.line_count} lines)")
+        w("")
+        w("```markdown")
+        w(skill.content.rstrip())
+        w("```")
+        w("")
+
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# SKILLS-REFERENCE.md generator
+# ---------------------------------------------------------------------------
+
+def group_skills_by(skills: list[Skill]) -> dict[str, list[Skill]]:
+    """Group shipped skills by their group field."""
+    groups: dict[str, list[Skill]] = {}
+    for s in skills:
+        groups.setdefault(s.group, []).append(s)
+    return groups
+
+
+def dev_category_for(filename: str) -> str:
+    """Find which dev category a filename belongs to."""
+    for cat, members in DEV_CATEGORIES.items():
+        if filename in members:
+            return cat
+    return "Other"
+
+
+def tools_cell(tools: list[str]) -> str:
+    """Format tools list for a table cell."""
+    if not tools:
+        return "*(none)*"
+    return ", ".join(tools)
+
+
+def tool_matrix_row(skill: Skill, all_tools: list[str]) -> str:
+    """Generate a tool access matrix row."""
+    cells = []
+    for t in all_tools:
+        # Handle mcp__context7__* wildcard
+        if t in skill.tools:
+            cells.append("x")
+        else:
+            # Check for mcp prefix tools
+            has_mcp = any(tool.startswith("mcp__") for tool in skill.tools)
+            if t == "mcp" and has_mcp:
+                cells.append("x")
+            else:
+                cells.append("")
+    name = skill.command.replace("/pan:", "")
+    return f"| {name} | " + " | ".join(cells) + " |"
+
+
+def generate_reference(shipped: list[Skill], dev: list[Skill], version: str) -> str:
+    """Generate the reference summary document."""
+    lines = []
+    w = lines.append
+
+    w("# PAN Wizard — Skills Reference")
+    w("")
+    w("Complete catalog of every skill (slash command) available in PAN Wizard, organized by purpose.")
+    w("Each entry shows the command, what it does, what tools it uses, and when to reach for it.")
+    w("")
+    w(f"**Version:** {version} | **Total:** {len(shipped)} shipped skills + {len(dev)} dev skills = {len(shipped) + len(dev)}")
+    w("")
+    w("> Auto-generated by `scripts/generate-skills-docs.py` — do not edit manually.")
+    w("")
+    w("---")
+    w("")
+
+    # ── Table of Contents ──
+    grouped = group_skills_by(shipped)
+    ordered_groups = [g for g in GROUP_ORDER if g in grouped]
+    # Add any groups not in GROUP_ORDER
+    for g in grouped:
+        if g not in ordered_groups:
+            ordered_groups.append(g)
+
+    w("## Table of Contents")
+    w("")
+    w(f"- [Shipped Skills ({len(shipped)})](#shipped-skills-{len(shipped)}) — installed into host projects")
+    for g in ordered_groups:
+        anchor = g.lower().replace(" & ", "--").replace(" ", "-")
+        w(f"  - [{g}](#{anchor})")
+    w(f"- [Dev Skills ({len(dev)})](#dev-skills-{len(dev)}) — PAN source repo only")
+    for cat in DEV_CATEGORIES:
+        anchor = cat.lower().replace(" & ", "--").replace(" ", "-")
+        w(f"  - [{cat}](#{anchor})")
+    w("")
+    w("---")
+    w("")
+
+    # ── Shipped Skills ──
+    w(f"## Shipped Skills ({len(shipped)})")
+    w("")
+    w("These are installed into host projects via the PAN installer and available to end users.")
+    w("")
+
+    for group_name in ordered_groups:
+        group_skills = grouped[group_name]
+        w(f"### {group_name}")
+        w("")
+
+        # Summary table
+        w("| Skill | Tools | Description |")
+        w("|-------|-------|-------------|")
+        for s in group_skills:
+            w(f"| `{s.command}` | {tools_cell(s.tools)} | {s.description} |")
+        w("")
+
+        # Individual entries
+        for s in group_skills:
+            w(f"#### {s.command}")
+            w("")
+            if s.description:
+                w(s.description)
+                w("")
+            if s.argument_hint:
+                w(f"```")
+                w(f"{s.command} {s.argument_hint}")
+                w(f"```")
+            else:
+                w(f"```")
+                w(f"{s.command}")
+                w(f"```")
+            w("")
+            w(f"**Tools:** {tools_cell(s.tools)}  ")
+            w(f"**Group:** {s.group}  ")
+            w(f"**Lines:** {s.line_count}")
+            w("")
+
+        w("---")
+        w("")
+
+    # ── Dev Skills ──
+    w(f"## Dev Skills ({len(dev)})")
+    w("")
+    w("These exist only in the PAN source repository (`.claude/commands/`) and are NOT shipped to end users.")
+    w("")
+
+    dev_by_cat: dict[str, list[Skill]] = {}
+    for s in dev:
+        cat = dev_category_for(s.filename)
+        dev_by_cat.setdefault(cat, []).append(s)
+
+    for cat_name in DEV_CATEGORIES:
+        if cat_name not in dev_by_cat:
+            continue
+        cat_skills = dev_by_cat[cat_name]
+        w(f"### {cat_name}")
+        w("")
+        w("| Skill | Description |")
+        w("|-------|-------------|")
+        for s in cat_skills:
+            desc = s.description or s.heading or s.filename
+            w(f"| `{s.command}` | {desc} |")
+        w("")
+
+        for s in cat_skills:
+            w(f"#### {s.command}")
+            w("")
+            desc = s.description or s.heading or ""
+            if desc:
+                w(desc)
+                w("")
+            w(f"**Lines:** {s.line_count}")
+            w("")
+
+        w("---")
+        w("")
+
+    # Handle any dev skills not in a named category
+    other_skills = dev_by_cat.get("Other", [])
+    if other_skills:
+        w("### Other")
+        w("")
+        w("| Skill | Description |")
+        w("|-------|-------------|")
+        for s in other_skills:
+            desc = s.description or s.heading or s.filename
+            w(f"| `{s.command}` | {desc} |")
+        w("")
+        for s in other_skills:
+            w(f"#### {s.command}")
+            w("")
+            if s.description:
+                w(s.description)
+                w("")
+            w(f"**Lines:** {s.line_count}")
+            w("")
+        w("---")
+        w("")
+
+    # ── Tool Access Matrix ──
+    w("## Tool Access Matrix")
+    w("")
+    w("Which tools each shipped skill can use:")
+    w("")
+
+    # Header
+    tool_short = ["Read", "Write", "Edit", "Bash", "Grep", "Glob",
+                   "Agent", "Task", "TodoWrite", "AskUser",
+                   "SlashCmd", "WebSearch", "WebFetch", "mcp"]
+    tool_full = ["Read", "Write", "Edit", "Bash", "Grep", "Glob",
+                  "Agent", "Task", "TodoWrite", "AskUserQuestion",
+                  "SlashCommand", "WebSearch", "WebFetch"]
+    header = "| Skill | " + " | ".join(tool_short) + " |"
+    sep = "|-------|" + "|".join([":---:" for _ in tool_short]) + "|"
+    w(header)
+    w(sep)
+
+    for s in shipped:
+        cells = []
+        for short, full in zip(tool_short, tool_full + ["mcp"]):
+            if full == "mcp":
+                has_mcp = any(t.startswith("mcp__") for t in s.tools)
+                cells.append("x" if has_mcp else "")
+            elif full in s.tools:
+                cells.append("x")
+            else:
+                cells.append("")
+        name = s.command.replace("/pan:", "")
+        w(f"| {name} | " + " | ".join(cells) + " |")
+
+    w("")
+
+    # ── Quick Reference ──
+    w("---")
+    w("")
+    w("## Quick Reference — Common Workflows")
+    w("")
+    w("| Scenario | Skill sequence |")
+    w("|----------|---------------|")
+    w("| Greenfield project | `new-project` > `discuss-phase` > `plan-phase` > `exec-phase` > `verify-phase` |")
+    w("| Brownfield project | `map-codebase` > `new-project` > `discuss-phase` > `plan-phase` > `exec-phase` > `verify-phase` |")
+    w("| Quick bug fix | `quick` |")
+    w("| Substantial ad-hoc work | `quick --full` |")
+    w("| Start of day | `progress` > `resume` |")
+    w("| End of day | `pause` |")
+    w("| New version cycle | `milestone-done` > `milestone-new` |")
+    w("| Automated from PRD | `new-project --auto @prd.md` > `plan-phase --auto` > `exec-phase` > `verify-phase` |")
+    w("| Continuous improvement | `focus-auto --category <cat>` |")
+    w("| Execute micro-prompts | `focus-auto --category prompts` |")
+    w("| Feature investigation | `focus-design \"description\"` |")
+    w("| Doc hygiene | `focus-drift-walking` or `focus-doc-audit` |")
+    w("")
+
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main():
+    dry_run = "--dry-run" in sys.argv
+    full_only = "--full-only" in sys.argv
+    ref_only = "--ref-only" in sys.argv
+
+    version = get_version()
+    shipped = load_shipped_skills()
+    dev = load_dev_skills()
+
+    print(f"PAN Wizard v{version}")
+    print(f"Shipped skills: {len(shipped)} (from {SHIPPED_DIR})")
+    print(f"Dev skills:     {len(dev)} (from {DEV_DIR})")
+    print()
+
+    if not ref_only:
+        full_text = generate_full_text(shipped, dev, version)
+        full_lines = full_text.count("\n") + 1
+        if dry_run:
+            print(f"[dry-run] Would write {OUT_FULL_TEXT} ({full_lines} lines)")
+        else:
+            OUT_FULL_TEXT.write_text(full_text, encoding="utf-8")
+            print(f"Wrote {OUT_FULL_TEXT} ({full_lines} lines)")
+
+    if not full_only:
+        reference = generate_reference(shipped, dev, version)
+        ref_lines = reference.count("\n") + 1
+        if dry_run:
+            print(f"[dry-run] Would write {OUT_REFERENCE} ({ref_lines} lines)")
+        else:
+            OUT_REFERENCE.write_text(reference, encoding="utf-8")
+            print(f"Wrote {OUT_REFERENCE} ({ref_lines} lines)")
+
+    print()
+    print("Done.")
+
+
+if __name__ == "__main__":
+    main()