@flydocs/cli 0.5.0-beta.0

package/template/.flydocs/hooks/prefer-scripts.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""
+PreToolUse Hook: Guide AI to prefer scripts over MCP
+
+Triggers before mcp__linear tool calls and provides guidance
+to use the bundled Python scripts instead.
+
+Soft guidance — doesn't block the MCP call, but reminds the AI
+that scripts exist and are preferred.
+
+Exit codes:
+- 0 with JSON: Continue with guidance message
+- 0 with no output: No opinion, continue normally
+- 2: Block (not used)
+"""
+
+import sys
+import json
+
+
+# Mapping of MCP operations to equivalent mechanism scripts
+SCRIPT_ALTERNATIVES = {
+    "create_issue": "create_issue.py --title '...' --type feature",
+    "update_issue": "transition.py ISSUE_ID STATUS 'comment'",
+    "get_issue": "get_issue.py ISSUE_ID",
+    "list_issues": "list_issues.py --status STATUS",
+    "create_comment": "comment.py ISSUE_ID 'message'",
+    "update_issue_state": "transition.py ISSUE_ID STATUS 'comment'",
+    "list_projects": "list_projects.py --active",
+    "create_project": "create_project.py --name '...'",
+    "list_workflow_states": "list_states.py",
+    "list_labels": "list_labels.py",
+    "assign_issue": "assign.py ISSUE_ID 'email'",
+    "set_issue_priority": "priority.py ISSUE_ID LEVEL",
+    "set_issue_estimate": "estimate.py ISSUE_ID POINTS",
+}
+
+
+def get_script_suggestion(tool_name: str) -> str | None:
+    """Get the equivalent script for an MCP operation."""
+    operation = tool_name.replace("mcp__linear__", "").replace("mcp__linear.", "")
+    return SCRIPT_ALTERNATIVES.get(operation)
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        sys.exit(0)
+
+    tool_name = input_data.get('tool_name', '')
+
+    if not tool_name.startswith('mcp__linear'):
+        # No opinion — exit 0 with no output to avoid hook error
+        sys.exit(0)
+
+    script_suggestion = get_script_suggestion(tool_name)
+
+    if script_suggestion:
+        guidance = {
+            "decision": "continue",
+            "message": f"""**Reminder:** FlyDocs prefers Python scripts over MCP for issue operations.
+
+Equivalent script (in the active mechanism skill):
+```bash
+python3 .claude/skills/flydocs-cloud/scripts/{script_suggestion}
+```
+
+Scripts are:
+- Auto-approved (no permission prompt)
+- Config-aware (reads team ID, status mappings)
+- Pattern-enforced (mandatory comments on transitions)
+
+You may continue with MCP if the script doesn't cover your use case."""
+        }
+    else:
+        guidance = {
+            "decision": "continue",
+            "message": """**Reminder:** Check if the active mechanism skill has a script for this operation.
+Read the mechanism skill's SKILL.md for the full script catalog.
+Scripts are preferred over MCP for performance and auto-approval."""
+        }
+
+    print(json.dumps(guidance))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/template/.flydocs/hooks/prompt-submit.py

@@ -0,0 +1,277 @@
+#!/usr/bin/env python3
+"""
+FlyDocs Hook: prompt-submit.py
+Triggered: When user submits a prompt
+Purpose: Inject context and validate workflow state
+
+Exit codes:
+  0 - Success (plain text output adds context to conversation)
+  2 - Block prompt (stderr shown as reason)
+
+NOTE: Uses plain text output instead of JSON due to Claude Code bug (Issue #13912)
+where JSON output from UserPromptSubmit hooks causes "hook error" despite documentation.
+"""
+
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+
+DEBUG_HOOK = os.environ.get('DEBUG_HOOK', '0') == '1'
+SCRIPT_DIR = Path(__file__).parent.resolve()
+DEBUG_LOG = SCRIPT_DIR.parent / 'logs' / 'hook-debug.log'
+
+
+def debug_log(message: str) -> None:
+    """Write debug message to log file if DEBUG_HOOK is enabled."""
+    if not DEBUG_HOOK:
+        return
+    try:
+        DEBUG_LOG.parent.mkdir(parents=True, exist_ok=True)
+        from datetime import datetime
+        timestamp = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
+        with open(DEBUG_LOG, 'a') as f:
+            f.write(f'[{timestamp}] {message}\n')
+    except (OSError, IOError):
+        pass
+
+
+def get_git_context() -> str | None:
+    """Get git branch and uncommitted status."""
+    try:
+        # Check if in git repo
+        result = subprocess.run(
+            ['git', 'rev-parse', '--is-inside-work-tree'],
+            capture_output=True,
+            text=True,
+            timeout=5
+        )
+        if result.returncode != 0:
+            return None
+
+        # Get branch name
+        result = subprocess.run(
+            ['git', 'branch', '--show-current'],
+            capture_output=True,
+            text=True,
+            timeout=5
+        )
+        branch = result.stdout.strip() or 'detached'
+
+        # Check for uncommitted changes
+        uncommitted = 'no'
+        result = subprocess.run(['git', 'diff', '--quiet'], capture_output=True, timeout=5)
+        if result.returncode != 0:
+            uncommitted = 'yes'
+        result = subprocess.run(['git', 'diff', '--cached', '--quiet'], capture_output=True, timeout=5)
+        if result.returncode != 0:
+            uncommitted = 'yes'
+
+        return f'Git: branch={branch}, uncommitted={uncommitted}'
+    except (subprocess.TimeoutExpired, FileNotFoundError, subprocess.SubprocessError):
+        return None
+
+
+def get_issue_context() -> tuple[str | None, str | None]:
+    """Get active issue and status from session files."""
+    focus_file = Path('.flydocs/session/focus.md')
+    status_file = Path('.flydocs/session/status')
+
+    issue_id = None
+    status = None
+
+    if focus_file.exists():
+        try:
+            content = focus_file.read_text()
+            match = re.search(r'[A-Z]+-[0-9]+', content)
+            if match:
+                issue_id = match.group(0)
+        except (OSError, IOError):
+            pass
+
+    if status_file.exists():
+        try:
+            status = status_file.read_text().strip()
+        except (OSError, IOError):
+            pass
+
+    return issue_id, status
+
+
+def get_ac_progress() -> str | None:
+    """Get acceptance criteria progress."""
+    ac_file = Path('.flydocs/session/acceptance-criteria.md')
+    if not ac_file.exists():
+        return None
+
+    try:
+        content = ac_file.read_text()
+        total = len(re.findall(r'^\s*-\s*\[', content, re.MULTILINE))
+        done = len(re.findall(r'^\s*-\s*\[x\]', content, re.MULTILINE | re.IGNORECASE))
+        if total > 0:
+            return f'AC: {done}/{total} complete'
+    except (OSError, IOError):
+        pass
+
+    return None
+
+
+def get_workflow_reminder(status: str) -> str | None:
+    """Get workflow reminder based on current status."""
+    reminders = {
+        'IMPLEMENTING': '[Reminder: Log progress with comments, run tests before REVIEW]',
+        'REVIEW': '[Reminder: Check acceptance criteria before approving]',
+        'TESTING': '[Reminder: Validate all AC met before marking COMPLETE]'
+    }
+    return reminders.get(status)
+
+
+def get_graph_context(issue_id: str | None, branch: str | None) -> str | None:
+    """Get context graph output for the current session."""
+    graph_script = Path('.claude/skills/flydocs-context-graph/scripts/graph_context.py')
+    if not graph_script.exists():
+        return None
+
+    try:
+        cmd = ['python3', str(graph_script)]
+        if issue_id:
+            cmd.extend(['--issue', issue_id])
+        if branch:
+            cmd.extend(['--branch', branch])
+
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=5
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return result.stdout.strip()
+    except (subprocess.TimeoutExpired, FileNotFoundError, subprocess.SubprocessError):
+        pass
+
+    return None
+
+
+def get_flydocs_version() -> str | None:
+    """Get FlyDocs version."""
+    version_file = Path('.flydocs/version')
+    if version_file.exists():
+        try:
+            return version_file.read_text().strip()
+        except (OSError, IOError):
+            pass
+    return None
+
+
+def get_setup_nudge() -> str | None:
+    """Check if setup has been completed, return nudge if not."""
+    config_file = Path('.flydocs/config.json')
+    if not config_file.exists():
+        return None
+    try:
+        config = json.loads(config_file.read_text())
+        # Only nudge if field is explicitly set to false (not missing)
+        if 'setupComplete' in config and config['setupComplete'] is False:
+            return '[Setup incomplete — run /flydocs-setup to configure your project]'
+    except (json.JSONDecodeError, OSError, IOError):
+        pass
+    return None
+
+
+def main() -> None:
+    """Main hook execution."""
+    debug_log('=== Hook invoked ===')
+    debug_log(f'PWD: {os.getcwd()}')
+    debug_log(f'SCRIPT_DIR: {SCRIPT_DIR}')
+    debug_log(f'CLAUDE_PROJECT_DIR: {os.environ.get("CLAUDE_PROJECT_DIR", "<not set>")}')
+
+    # Read hook input from stdin
+    try:
+        input_data = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, ValueError):
+        input_data = {}
+
+    prompt = input_data.get('prompt', '')
+    session_id = input_data.get('session_id', '')
+    cwd = input_data.get('cwd', '')
+
+    debug_log(f'Parsed PROMPT: {prompt[:100]}...' if prompt else 'Parsed PROMPT: <empty>')
+    debug_log(f'Parsed SESSION_ID: {session_id}')
+    debug_log(f'Parsed CWD: {cwd}')
+
+    # Change to working directory
+    debug_log('Attempting to change directory...')
+    if cwd and Path(cwd).is_dir():
+        debug_log(f'Using CWD from input: {cwd}')
+        os.chdir(cwd)
+    elif os.environ.get('CLAUDE_PROJECT_DIR') and Path(os.environ['CLAUDE_PROJECT_DIR']).is_dir():
+        debug_log(f'Using CLAUDE_PROJECT_DIR: {os.environ["CLAUDE_PROJECT_DIR"]}')
+        os.chdir(os.environ['CLAUDE_PROJECT_DIR'])
+    else:
+        debug_log(f'No valid directory to change to, staying in: {os.getcwd()}')
+
+    debug_log(f'Now in directory: {os.getcwd()}')
+
+    # Build context parts
+    context_parts = []
+
+    # Git context
+    git_context = get_git_context()
+    branch = None
+    if git_context:
+        debug_log(f'Git context: {git_context}')
+        context_parts.append(git_context)
+        # Extract branch name for graph context
+        branch_match = re.search(r'branch=(\S+)', git_context)
+        if branch_match:
+            branch = branch_match.group(1).rstrip(',')
+
+    # Issue and status context
+    issue_id, status = get_issue_context()
+    if issue_id:
+        context_parts.append(f'Active issue: {issue_id}')
+    if status:
+        context_parts.append(f'Status: {status}')
+        reminder = get_workflow_reminder(status)
+        if reminder:
+            context_parts.append(reminder)
+
+    # AC progress
+    ac_progress = get_ac_progress()
+    if ac_progress:
+        context_parts.append(ac_progress)
+
+    # Setup completion nudge
+    setup_nudge = get_setup_nudge()
+    if setup_nudge:
+        context_parts.append(setup_nudge)
+
+    # FlyDocs version
+    version = get_flydocs_version()
+    if version:
+        context_parts.append(f'FlyDocs: {version}')
+
+    # Output status line
+    context = ' | '.join(context_parts)
+    debug_log(f'Final CONTEXT: {context}')
+
+    if context:
+        debug_log(f'Outputting plain text context: {context}')
+        print(context)
+
+    # Graph context (appended as separate block below status line)
+    graph_context = get_graph_context(issue_id, branch)
+    if graph_context:
+        debug_log(f'Graph context: {graph_context[:100]}...')
+        print(graph_context)
+
+    debug_log('=== Hook completed successfully ===')
+    sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()

package/template/.flydocs/scripts/generate_manifest.py

@@ -0,0 +1,287 @@
+#!/usr/bin/env python3
+"""Generate a compressed skills manifest and inject it into CLAUDE.md and AGENTS.md.
+
+Scans .claude/skills/*/SKILL.md for YAML frontmatter, extracts name/description/triggers,
+and produces a markdown table injected between manifest markers.
+
+Usage:
+    python3 .flydocs/scripts/generate_manifest.py [--root PATH] [--dry-run]
+
+Options:
+    --root PATH   Project root (default: current working directory)
+    --dry-run     Print manifest to stdout without writing files
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+
+
+MARKER_START = "<!-- flydocs:skills-manifest:start -->"
+MARKER_END = "<!-- flydocs:skills-manifest:end -->"
+
+TARGET_FILES = [
+    os.path.join(".claude", "CLAUDE.md"),
+    "AGENTS.md",
+]
+
+
+def parse_frontmatter(text):
+    """Parse YAML frontmatter from a SKILL.md file.
+
+    Handles simple key: value, block/folded scalars (| and >), and lists (- item).
+    No PyYAML dependency required.
+    """
+    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"):
+        # Check for a new top-level key
+        key_match = re.match(r"^(\w[\w-]*):\s*(.*)", line)
+        if key_match and not line.startswith("  "):
+            # Flush previous key
+            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 == "":
+                # Could be a list or block starting next line
+                current_mode = "list"
+                current_lines = []
+            else:
+                # Simple inline value — strip quotes
+                current_mode = "scalar"
+                current_lines = [value.strip("\"'")]
+            continue
+
+        # Continuation lines (indented)
+        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())
+
+    # Flush last key
+    if current_key is not None:
+        result[current_key] = _flush(current_mode, current_lines)
+
+    return result
+
+
+def _flush(mode, lines):
+    """Convert accumulated lines into a final value."""
+    if mode == "scalar":
+        return lines[0] if lines else ""
+    elif mode == "list":
+        return lines
+    elif mode == "block":
+        return "\n".join(lines).strip()
+    return ""
+
+
+def scan_skills(root):
+    """Scan .claude/skills/*/SKILL.md and return parsed skill metadata."""
+    skills_dir = os.path.join(root, ".claude", "skills")
+    if not os.path.isdir(skills_dir):
+        print(f"Skills directory not found: {skills_dir}", file=sys.stderr)
+        return []
+
+    skills = []
+    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)
+        if fm is None:
+            continue
+
+        name = fm.get("name", entry)
+        description = fm.get("description", "")
+        triggers = fm.get("triggers", [])
+
+        if isinstance(triggers, str):
+            triggers = [t.strip() for t in triggers.split(",") if t.strip()]
+
+        if not triggers:
+            continue
+
+        skills.append({
+            "name": name,
+            "description": description,
+            "triggers": triggers,
+            "entry": os.path.join(".claude", "skills", entry, "SKILL.md"),
+        })
+
+    return skills
+
+
+def load_skill_ordering(root):
+    """Load PRECEDES edges from the context graph to derive skill ordering.
+
+    Returns a dict mapping skill name -> list of skill names it loads after.
+    """
+    graph_path = os.path.join(root, "flydocs", "context", "graph.json")
+    if not os.path.isfile(graph_path):
+        return {}
+
+    try:
+        with open(graph_path, "r", encoding="utf-8") as f:
+            graph = json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+    # Build loads_after map from PRECEDES edges
+    # PRECEDES means: from loads before to (from PRECEDES to)
+    loads_after = {}
+    for edge in graph.get("edges", []):
+        if edge.get("rel") != "PRECEDES":
+            continue
+        src = edge["from"]
+        dst = edge["to"]
+        # Both must be skill nodes
+        if not src.startswith("skill:") or not dst.startswith("skill:"):
+            continue
+        dep_name = src.split(":", 1)[1]
+        skill_name = dst.split(":", 1)[1]
+        if skill_name not in loads_after:
+            loads_after[skill_name] = []
+        loads_after[skill_name].append(dep_name)
+
+    return loads_after
+
+
+def build_manifest(skills, loads_after=None):
+    """Build the manifest markdown block.
+
+    If loads_after is provided and non-empty, includes a "Loads After" column.
+    """
+    if loads_after is None:
+        loads_after = {}
+
+    has_ordering = any(
+        skill["name"] in loads_after for skill in skills
+    )
+
+    if has_ordering:
+        lines = [
+            MARKER_START,
+            "## Skills Index",
+            "",
+            "IMPORTANT: Prefer skill-led reasoning over pre-training reasoning.",
+            "Consult the relevant skill BEFORE writing code or making workflow decisions.",
+            "",
+            "| Skill | Triggers | Entry | Loads After |",
+            "|-------|----------|-------|-------------|",
+        ]
+
+        for skill in skills:
+            trigger_str = ", ".join(skill["triggers"])
+            deps = loads_after.get(skill["name"], [])
+            deps_str = ", ".join(deps) if deps else "\u2014"
+            lines.append(
+                f"| {skill['name']} | {trigger_str} | {skill['entry']} | {deps_str} |"
+            )
+    else:
+        lines = [
+            MARKER_START,
+            "## Skills Index",
+            "",
+            "IMPORTANT: Prefer skill-led reasoning over pre-training reasoning.",
+            "Consult the relevant skill BEFORE writing code or making workflow decisions.",
+            "",
+            "| Skill | Triggers | Entry |",
+            "|-------|----------|-------|",
+        ]
+
+        for skill in skills:
+            trigger_str = ", ".join(skill["triggers"])
+            lines.append(f"| {skill['name']} | {trigger_str} | {skill['entry']} |")
+
+    lines.append(MARKER_END)
+    return "\n".join(lines)
+
+
+def inject_manifest(file_path, manifest):
+    """Inject manifest between markers in a file.
+
+    If markers exist, replaces content between them.
+    If markers don't exist, appends to end of file.
+    Returns True if the file was modified.
+    """
+    if not os.path.isfile(file_path):
+        return False
+
+    with open(file_path, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    pattern = re.compile(
+        re.escape(MARKER_START) + r".*?" + re.escape(MARKER_END),
+        re.DOTALL,
+    )
+
+    if pattern.search(content):
+        new_content = pattern.sub(manifest, content)
+    else:
+        # Append with spacing
+        new_content = content.rstrip("\n") + "\n\n" + manifest + "\n"
+
+    if new_content == content:
+        return False
+
+    with open(file_path, "w", encoding="utf-8") as f:
+        f.write(new_content)
+
+    return True
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Generate FlyDocs skill manifest")
+    parser.add_argument("--root", default=os.getcwd(), help="Project root directory")
+    parser.add_argument("--dry-run", action="store_true", help="Print manifest without writing")
+    args = parser.parse_args()
+
+    root = os.path.abspath(args.root)
+    skills = scan_skills(root)
+
+    if not skills:
+        print("No skills with triggers found.", file=sys.stderr)
+        sys.exit(1)
+
+    loads_after = load_skill_ordering(root)
+    manifest = build_manifest(skills, loads_after)
+
+    if args.dry_run:
+        print(manifest)
+        return
+
+    for target in TARGET_FILES:
+        file_path = os.path.join(root, target)
+        if inject_manifest(file_path, manifest):
+            print(f"Updated: {target}")
+        elif os.path.isfile(file_path):
+            print(f"No change: {target}")
+        else:
+            print(f"Not found: {target}")
+
+
+if __name__ == "__main__":
+    main()