@flydocs/cli 0.5.0-beta.0

package/template/.flydocs/scripts/skill_manager.py

@@ -0,0 +1,541 @@
+#!/usr/bin/env python3
+"""FlyDocs Skill Manager — search, add, remove, and list community skills.
+
+Usage:
+    python3 skill_manager.py search <keyword>
+    python3 skill_manager.py add <source>
+    python3 skill_manager.py remove <name>
+    python3 skill_manager.py list
+
+Source formats for add:
+    Known name:      react-best-practices
+    Repo reference:  vercel-labs/agent-skills:react-best-practices
+    GitHub URL:      https://github.com/owner/repo/tree/main/skills/name
+"""
+
+import argparse
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+
+
+RED = "\033[0;31m"
+GREEN = "\033[0;32m"
+BLUE = "\033[0;34m"
+YELLOW = "\033[1;33m"
+CYAN = "\033[0;36m"
+NC = "\033[0m"
+
+# ─── Curated community skills catalog ────────────────────────────────────────
+# Mirrors install.sh COMMUNITY_SKILLS_MAP. Designed to swap with real API later.
+
+COMMUNITY_SKILLS = [
+    {
+        "name": "react-best-practices",
+        "repo": "vercel-labs/agent-skills",
+        "description": "React/Next.js performance optimization (40+ rules from Vercel)",
+        "tags": ["react", "nextjs", "performance", "components"],
+    },
+    {
+        "name": "web-design-guidelines",
+        "repo": "vercel-labs/agent-skills",
+        "description": "UI/UX accessibility and design patterns (100+ rules)",
+        "tags": ["design", "accessibility", "ux", "ui", "nextjs", "web"],
+    },
+    {
+        "name": "convex-best-practices",
+        "repo": "waynesutton/convexskills",
+        "description": "Convex database patterns and best practices",
+        "tags": ["convex", "database", "backend"],
+    },
+    {
+        "name": "convex-functions",
+        "repo": "waynesutton/convexskills",
+        "description": "Convex query/mutation/action patterns",
+        "tags": ["convex", "functions", "query", "mutation"],
+    },
+    {
+        "name": "tailwind-v4",
+        "repo": "blencorp/claude-code-kit",
+        "description": "Tailwind CSS v4 patterns and configuration",
+        "tags": ["tailwind", "css", "styling"],
+    },
+    {
+        "name": "clerk-auth",
+        "repo": "blencorp/claude-code-kit",
+        "description": "Clerk authentication patterns",
+        "tags": ["clerk", "auth", "authentication"],
+    },
+]
+
+
+# ─── Helpers ──────────────────────────────────────────────────────────────────
+
+
+def find_project_root():
+    """Find the project root by walking up to .flydocs/config.json."""
+    path = os.getcwd()
+    while True:
+        if os.path.isfile(os.path.join(path, ".flydocs", "config.json")):
+            return path
+        parent = os.path.dirname(path)
+        if parent == path:
+            break
+        path = parent
+    return os.getcwd()
+
+
+def load_config(root):
+    """Load .flydocs/config.json."""
+    config_path = os.path.join(root, ".flydocs", "config.json")
+    if not os.path.isfile(config_path):
+        print(f"{RED}✗{NC} No .flydocs/config.json found. Is FlyDocs installed?", file=sys.stderr)
+        sys.exit(1)
+    with open(config_path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def save_config(root, config):
+    """Save .flydocs/config.json."""
+    config_path = os.path.join(root, ".flydocs", "config.json")
+    with open(config_path, "w", encoding="utf-8") as f:
+        json.dump(config, f, indent=2)
+        f.write("\n")
+
+
+def parse_frontmatter(text):
+    """Parse YAML frontmatter from a SKILL.md file.
+
+    Duplicated from generate_manifest.py — each script is self-contained.
+    """
+    match = re.match(r"^---\s*\n(.*?)\n---", text, re.DOTALL)
+    if not match:
+        return None
+
+    block = match.group(1)
+    result = {}
+    current_key = None
+    current_mode = None  # "scalar", "block", "list"
+    current_lines = []
+
+    for line in block.split("\n"):
+        key_match = re.match(r"^(\w[\w-]*):\s*(.*)", line)
+        if key_match and not line.startswith("  "):
+            if current_key is not None:
+                result[current_key] = _flush(current_mode, current_lines)
+
+            current_key = key_match.group(1)
+            value = key_match.group(2).strip()
+
+            if value in ("|", ">"):
+                current_mode = "block"
+                current_lines = []
+            elif value == "":
+                current_mode = "list"
+                current_lines = []
+            else:
+                current_mode = "scalar"
+                current_lines = [value.strip("\"'")]
+            continue
+
+        stripped = line.strip()
+        if current_key is not None:
+            if current_mode == "list" and stripped.startswith("- "):
+                current_lines.append(stripped[2:].strip().strip("\"'"))
+            elif current_mode == "block":
+                current_lines.append(line.lstrip())
+
+    if current_key is not None:
+        result[current_key] = _flush(current_mode, current_lines)
+
+    return result
+
+
+def _flush(mode, lines):
+    if mode == "scalar":
+        return lines[0] if lines else ""
+    elif mode == "list":
+        return lines
+    elif mode == "block":
+        return "\n".join(lines).strip()
+    return ""
+
+
+def is_platform_skill(name):
+    """Check if a skill name is platform-managed."""
+    return name.startswith("flydocs-")
+
+
+def regenerate_manifest(root):
+    """Run generate_manifest.py to update CLAUDE.md/AGENTS.md."""
+    script = os.path.join(root, ".flydocs", "scripts", "generate_manifest.py")
+    if not os.path.isfile(script):
+        print(f"{YELLOW}⚠{NC} generate_manifest.py not found — skipping manifest update.")
+        return
+
+    try:
+        subprocess.run(
+            [sys.executable, script, "--root", root],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        print(f"{GREEN}✓{NC} Regenerated skill manifest")
+    except subprocess.CalledProcessError as e:
+        print(f"{YELLOW}⚠{NC} Manifest regeneration failed: {e.stderr.strip()}")
+
+
+# ─── search ──────────────────────────────────────────────────────────────────
+
+
+def cmd_search(args):
+    """Search curated community skills catalog."""
+    keyword = args.keyword.lower()
+    matches = []
+
+    for skill in COMMUNITY_SKILLS:
+        searchable = f"{skill['name']} {skill['description']} {' '.join(skill['tags'])}".lower()
+        if keyword in searchable:
+            matches.append(skill)
+
+    if not matches:
+        print(f"\n  No skills found matching '{args.keyword}'.")
+        print(f"  Browse more at: https://skills.sh/\n")
+        return
+
+    print(f"\n  Found {len(matches)} skill(s) matching '{args.keyword}':\n")
+    for skill in matches:
+        print(f"  {CYAN}{skill['name']}{NC}")
+        print(f"    {skill['description']}")
+        print(f"    Source: {skill['repo']}")
+        print(f"    Tags: {', '.join(skill['tags'])}")
+        print()
+
+    print(f"  Install with: flydocs skills add <name>")
+    print(f"  Browse more at: https://skills.sh/\n")
+
+
+# ─── add ─────────────────────────────────────────────────────────────────────
+
+
+def parse_source(source):
+    """Parse a skill source into (repo, skill_name).
+
+    Accepts:
+      - Known name: "react-best-practices"
+      - Repo reference: "vercel-labs/agent-skills:react-best-practices"
+      - GitHub URL: "https://github.com/owner/repo/tree/main/skills/name"
+    """
+    # GitHub URL
+    url_match = re.match(
+        r"https?://github\.com/([^/]+/[^/]+)/tree/[^/]+/skills/([^/]+)/?$",
+        source,
+    )
+    if url_match:
+        return url_match.group(1), url_match.group(2)
+
+    # Repo reference (owner/repo:skill-name)
+    if ":" in source:
+        repo, name = source.rsplit(":", 1)
+        if "/" in repo:
+            return repo, name
+
+    # Known name — lookup in curated catalog
+    for skill in COMMUNITY_SKILLS:
+        if skill["name"] == source:
+            return skill["repo"], skill["name"]
+
+    print(f"{RED}✗{NC} Unknown skill: {source}", file=sys.stderr)
+    print(f"  Try: flydocs skills search <keyword>", file=sys.stderr)
+    print(f"  Or use full reference: owner/repo:skill-name", file=sys.stderr)
+    sys.exit(1)
+
+
+def download_skill_tree(repo, skill_name, target_dir):
+    """Download a skill directory tree via GitHub Contents API (recursive)."""
+    api_url = f"https://api.github.com/repos/{repo}/contents/skills/{skill_name}"
+
+    def fetch_json(url):
+        req = urllib.request.Request(url, headers={"User-Agent": "flydocs-cli"})
+        try:
+            with urllib.request.urlopen(req, timeout=15) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            if e.code == 404:
+                return None
+            raise
+
+    def download_recursive(url, dest_dir):
+        items = fetch_json(url)
+        if items is None:
+            return False
+
+        # Single file response comes as dict, directory as list
+        if isinstance(items, dict):
+            items = [items]
+
+        os.makedirs(dest_dir, exist_ok=True)
+
+        for item in items:
+            dest_path = os.path.join(dest_dir, item["name"])
+            if item["type"] == "file":
+                if item.get("download_url"):
+                    req = urllib.request.Request(
+                        item["download_url"],
+                        headers={"User-Agent": "flydocs-cli"},
+                    )
+                    with urllib.request.urlopen(req, timeout=15) as resp:
+                        content = resp.read()
+                    with open(dest_path, "wb") as f:
+                        f.write(content)
+            elif item["type"] == "dir":
+                download_recursive(item["url"], dest_path)
+
+        return True
+
+    return download_recursive(api_url, target_dir)
+
+
+def cmd_add(args):
+    """Install a community skill."""
+    root = find_project_root()
+    config = load_config(root)
+    source = args.source
+
+    # Platform guard (check before parse_source which would reject as "unknown")
+    if is_platform_skill(source):
+        print(f"{RED}✗{NC} Cannot install platform skill '{source}'.")
+        print(f"  Platform skills (flydocs-*) are managed by the installer.")
+        sys.exit(1)
+
+    repo, skill_name = parse_source(source)
+
+    # Platform guard (for repo references that resolve to a flydocs-* name)
+    if is_platform_skill(skill_name):
+        print(f"{RED}✗{NC} Cannot install platform skill '{skill_name}'.")
+        print(f"  Platform skills (flydocs-*) are managed by the installer.")
+        sys.exit(1)
+
+    # Already installed check
+    skills_dir = os.path.join(root, ".claude", "skills", skill_name)
+    if os.path.isdir(skills_dir):
+        print(f"{YELLOW}⚠{NC} Skill '{skill_name}' is already installed.")
+        print(f"  Remove first: flydocs skills remove {skill_name}")
+        sys.exit(1)
+
+    print(f"\n{BLUE}→{NC} Installing {CYAN}{skill_name}{NC} from {repo}...\n")
+
+    # Download
+    try:
+        success = download_skill_tree(repo, skill_name, skills_dir)
+    except Exception as e:
+        if os.path.isdir(skills_dir):
+            shutil.rmtree(skills_dir)
+        print(f"{RED}✗{NC} Download failed: {e}")
+        sys.exit(1)
+
+    if not success:
+        if os.path.isdir(skills_dir):
+            shutil.rmtree(skills_dir)
+        print(f"{RED}✗{NC} Skill not found at {repo}/skills/{skill_name}")
+        sys.exit(1)
+
+    # Validate SKILL.md exists
+    skill_md = os.path.join(skills_dir, "SKILL.md")
+    if not os.path.isfile(skill_md):
+        shutil.rmtree(skills_dir)
+        print(f"{RED}✗{NC} Invalid skill: SKILL.md not found.")
+        sys.exit(1)
+
+    # Validate frontmatter
+    with open(skill_md, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    fm = parse_frontmatter(content)
+    if fm is None or not fm.get("name") or not fm.get("description"):
+        shutil.rmtree(skills_dir)
+        print(f"{RED}✗{NC} Invalid skill: SKILL.md missing required frontmatter (name, description).")
+        sys.exit(1)
+
+    if not fm.get("triggers"):
+        print(f"{YELLOW}⚠{NC} SKILL.md has no triggers — skill won't appear in manifest index.")
+
+    print(f"{GREEN}✓{NC} Downloaded skill files")
+
+    # Copy cursor-rule.mdc if present
+    cursor_rule = os.path.join(skills_dir, "cursor-rule.mdc")
+    if os.path.isfile(cursor_rule):
+        cursor_rules_dir = os.path.join(root, ".cursor", "rules")
+        os.makedirs(cursor_rules_dir, exist_ok=True)
+        dest = os.path.join(cursor_rules_dir, f"{skill_name}.mdc")
+        shutil.copy2(cursor_rule, dest)
+        print(f"{GREEN}✓{NC} Installed cursor rule")
+
+    # Update config.json skills.installed[]
+    installed = config.get("skills", {}).get("installed", [])
+    entry = f"{repo}/{skill_name}"
+    if entry not in installed:
+        installed.append(entry)
+        if "skills" not in config:
+            config["skills"] = {"installed": [], "custom": []}
+        config["skills"]["installed"] = installed
+        save_config(root, config)
+        print(f"{GREEN}✓{NC} Updated config.json")
+
+    # Regenerate manifest
+    regenerate_manifest(root)
+
+    print(f"\n{GREEN}✓{NC} Installed {CYAN}{skill_name}{NC}\n")
+
+
+# ─── remove ──────────────────────────────────────────────────────────────────
+
+
+def cmd_remove(args):
+    """Remove an installed community skill."""
+    root = find_project_root()
+    config = load_config(root)
+    skill_name = args.name
+
+    # Platform guard
+    if is_platform_skill(skill_name):
+        print(f"{RED}✗{NC} Cannot remove platform skill '{skill_name}'.")
+        print(f"  Platform skills (flydocs-*) are managed by the installer.")
+        sys.exit(1)
+
+    skills_dir = os.path.join(root, ".claude", "skills", skill_name)
+    if not os.path.isdir(skills_dir):
+        print(f"{RED}✗{NC} Skill '{skill_name}' is not installed.")
+        sys.exit(1)
+
+    # Remove skill directory
+    shutil.rmtree(skills_dir)
+    print(f"{GREEN}✓{NC} Removed skill directory")
+
+    # Remove cursor rule
+    cursor_rule = os.path.join(root, ".cursor", "rules", f"{skill_name}.mdc")
+    if os.path.isfile(cursor_rule):
+        os.remove(cursor_rule)
+        print(f"{GREEN}✓{NC} Removed cursor rule")
+
+    # Update config.json
+    installed = config.get("skills", {}).get("installed", [])
+    config["skills"]["installed"] = [
+        s for s in installed if not s.endswith(f"/{skill_name}")
+    ]
+    save_config(root, config)
+    print(f"{GREEN}✓{NC} Updated config.json")
+
+    # Regenerate manifest
+    regenerate_manifest(root)
+
+    print(f"\n{GREEN}✓{NC} Removed {CYAN}{skill_name}{NC}\n")
+
+
+# ─── list ────────────────────────────────────────────────────────────────────
+
+
+def cmd_list(args):
+    """List all installed skills with type and trigger count."""
+    root = find_project_root()
+    skills_dir = os.path.join(root, ".claude", "skills")
+
+    if not os.path.isdir(skills_dir):
+        print(f"\n  No skills installed.\n")
+        return
+
+    platform = []
+    community = []
+
+    for entry in sorted(os.listdir(skills_dir)):
+        skill_file = os.path.join(skills_dir, entry, "SKILL.md")
+        if not os.path.isfile(skill_file):
+            continue
+
+        with open(skill_file, "r", encoding="utf-8") as f:
+            content = f.read()
+
+        fm = parse_frontmatter(content)
+        name = fm.get("name", entry) if fm else entry
+        triggers = fm.get("triggers", []) if fm else []
+        if isinstance(triggers, str):
+            triggers = [t.strip() for t in triggers.split(",") if t.strip()]
+
+        info = {
+            "name": name,
+            "dir": entry,
+            "type": "platform" if is_platform_skill(entry) else "community",
+            "triggers": len(triggers),
+        }
+
+        if info["type"] == "platform":
+            platform.append(info)
+        else:
+            community.append(info)
+
+    total = len(platform) + len(community)
+    if total == 0:
+        print(f"\n  No skills installed.\n")
+        return
+
+    print(f"\n  {total} skill(s) installed:\n")
+
+    if platform:
+        print(f"  {YELLOW}Platform{NC}")
+        for s in platform:
+            print(f"    {CYAN}{s['name']}{NC} ({s['triggers']} triggers)")
+
+    if community:
+        if platform:
+            print()
+        print(f"  {YELLOW}Community{NC}")
+        for s in community:
+            print(f"    {CYAN}{s['name']}{NC} ({s['triggers']} triggers)")
+
+    print()
+
+
+# ─── main ────────────────────────────────────────────────────────────────────
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="flydocs skills",
+        description="Manage FlyDocs skills — search, install, and remove community skills.",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    search_p = sub.add_parser("search", help="Search available community skills")
+    search_p.add_argument("keyword", help="Keyword to search for")
+
+    add_p = sub.add_parser("add", help="Install a community skill")
+    add_p.add_argument("source", help="Skill name, repo:name, or GitHub URL")
+
+    remove_p = sub.add_parser("remove", help="Remove an installed community skill")
+    remove_p.add_argument("name", help="Skill directory name")
+
+    sub.add_parser("list", help="List installed skills")
+
+    args = parser.parse_args()
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(1)
+
+    commands = {
+        "search": cmd_search,
+        "add": cmd_add,
+        "remove": cmd_remove,
+        "list": cmd_list,
+    }
+
+    commands[args.command](args)
+
+
+if __name__ == "__main__":
+    main()

package/template/.flydocs/templates/README.md

@@ -0,0 +1,46 @@
+# Issue Templates
+
+This folder contains templates for creating and refining Linear issues. Each template includes agent instructions to ensure consistent, high-quality issue structure.
+
+## Template Usage
+
+**Agents use these templates when:**
+- Creating new issues via `/capture`
+- Refining issues via `/refine`
+- Triaging quick captures with `triage` label
+
+**Humans use `quick-capture.md` in Linear** as the default template for fast idea/bug capture.
+
+## Available Templates
+
+| Template | Purpose | When to Use |
+|----------|---------|-------------|
+| `feature.md` | New functionality | Building something new with user story |
+| `bug.md` | Fix defects | Something is broken |
+| `chore.md` | Maintenance/cleanup | Refactoring, polish, improvements |
+| `idea.md` | Capture concepts | Rough ideas for future exploration |
+| `quick-capture.md` | Fast capture | Human entry in Linear (default template) |
+
+## Agent Instructions
+
+Each template contains `<!-- AGENT: ... -->` comments that guide the AI when filling out sections. These instructions are removed from the final issue in Linear.
+
+**Key principles:**
+1. Fill all `[bracketed]` sections with specific content
+2. Don't remove sections - mark as "N/A" if not applicable
+3. Be specific in acceptance criteria (testable, measurable)
+4. Include context about "why" not just "what"
+5. Reference project context from `{content-folder}/context/` when relevant
+
+## Template Evolution
+
+Update these templates as your workflow evolves:
+- Add sections that are consistently needed
+- Remove sections that are never used
+- Improve agent instructions based on what works
+
+Changes here apply to all future issues.
+
+
+
+