@flydocs/cli 0.6.0-alpha.3 → 0.6.0-alpha.30

package/template/{.flydocs → .claude/skills/flydocs-workflow}/scripts/generate_manifest.py

@@ -186,8 +186,8 @@ def build_manifest(skills, loads_after=None):
             MARKER_START,
             "## Skills Index",
             "",
-            "IMPORTANT: Prefer skill-led reasoning over pre-training reasoning.",
-            "Consult the relevant skill BEFORE writing code or making workflow decisions.",
+            "Consult the workflow skill for **issue operations and status transitions only**.",
+            "For general coding tasks, skip this \u2014 just write code.",
             "",
             "| Skill | Triggers | Entry | Loads After |",
             "|-------|----------|-------|-------------|",
@@ -205,8 +205,8 @@ def build_manifest(skills, loads_after=None):
             MARKER_START,
             "## Skills Index",
             "",
-            "IMPORTANT: Prefer skill-led reasoning over pre-training reasoning.",
-            "Consult the relevant skill BEFORE writing code or making workflow decisions.",
+            "Consult the workflow skill for **issue operations and status transitions only**.",
+            "For general coding tasks, skip this \u2014 just write code.",
             "",
             "| Skill | Triggers | Entry |",
             "|-------|----------|-------|",

package/template/.claude/skills/{flydocs-context-graph → flydocs-workflow}/scripts/graph_build.py

@@ -5,7 +5,7 @@ Scans skills (SKILL.md frontmatter) and ADRs (decisions/*.md cross-references)
 to produce flydocs/context/graph.json. Preserves manually-added nodes and edges.
 
 Usage:
-    python3 .claude/skills/flydocs-context-graph/scripts/graph_build.py [--root PATH]
+    python3 .claude/skills/flydocs-workflow/scripts/graph_build.py [--root PATH]
 """
 
 import argparse
@@ -201,6 +201,129 @@ def classify_relationship(context):
     return "RELATES_TO"
 
 
+# --- Service descriptor scanning ---
+
+
+def scan_service_descriptor(root):
+    """Scan flydocs/context/service.json and return repo node + edges."""
+    nodes = {}
+    edges = []
+
+    service_file = root / "flydocs" / "context" / "service.json"
+    if not service_file.is_file():
+        return nodes, edges
+
+    import json
+    try:
+        data = json.loads(service_file.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return nodes, edges
+
+    if data.get("version") not in (1, 2):
+        return nodes, edges
+
+    repo_slug = data.get("repoSlug", "")
+    if not repo_slug:
+        return nodes, edges
+
+    node_id = f"repo:{repo_slug}"
+    nodes[node_id] = {
+        "type": "repo",
+        "label": data.get("name", repo_slug),
+        "path": "flydocs/context/service.json",
+        "purpose": data.get("purpose", ""),
+        "stack": data.get("stack", []),
+    }
+
+    # Create CONSUMES edges from dependencies
+    for dep in data.get("dependencies", []):
+        service = dep.get("service", "")
+        if not service:
+            continue
+        target_id = f"repo:{service}"
+        edges.append({
+            "from": node_id,
+            "to": target_id,
+            "rel": "CONSUMES",
+            "weight": 1.0,
+            "interface": dep.get("interface", ""),
+            "description": dep.get("description", ""),
+        })
+
+    return nodes, edges
+
+
+def scan_sibling_descriptors(root):
+    """Scan sibling repos' service.json files for cross-repo edges.
+
+    Only reads descriptors from sibling directories that have .flydocs/ and
+    flydocs/context/service.json. Does NOT generate descriptors for other repos.
+    """
+    nodes = {}
+    edges = []
+
+    parent = root.parent
+    if not parent.is_dir():
+        return nodes, edges
+
+    try:
+        siblings = sorted(parent.iterdir())
+    except PermissionError:
+        return nodes, edges
+
+    for sibling in siblings:
+        if sibling == root or not sibling.is_dir():
+            continue
+        try:
+            if not (sibling / ".git").exists():
+                continue
+        except PermissionError:
+            continue
+
+        service_file = sibling / "flydocs" / "context" / "service.json"
+        if not service_file.is_file():
+            continue
+
+        import json
+        try:
+            data = json.loads(service_file.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            continue
+
+        if data.get("version") not in (1, 2):
+            continue
+
+        repo_slug = data.get("repoSlug", "")
+        if not repo_slug:
+            continue
+
+        node_id = f"repo:{repo_slug}"
+        nodes[node_id] = {
+            "type": "repo",
+            "label": data.get("name", repo_slug),
+            "path": str(service_file),
+            "purpose": data.get("purpose", ""),
+            "stack": data.get("stack", []),
+        }
+
+        # Create CONSUMES edges from this sibling's dependencies
+        for dep in data.get("dependencies", []):
+            service = dep.get("service", "")
+            if not service:
+                continue
+            target_id = f"repo:{service}"
+            edges.append({
+                "from": node_id,
+                "to": target_id,
+                "rel": "CONSUMES",
+                "weight": 1.0,
+                "interface": dep.get("interface", ""),
+                "description": dep.get("description", ""),
+            })
+
+    return nodes, edges
+
+
 # --- Graph merge ---
 
 
@@ -263,15 +386,21 @@ def main():
     # Scan sources
     skill_nodes, skill_edges = scan_skills(root)
     adr_nodes, adr_edges = scan_adrs(root)
+    service_nodes, service_edges = scan_service_descriptor(root)
+    sibling_nodes, sibling_edges = scan_sibling_descriptors(root)
 
     # Merge all scanned nodes and edges
     all_nodes = {}
     all_nodes.update(skill_nodes)
     all_nodes.update(adr_nodes)
+    all_nodes.update(service_nodes)
+    all_nodes.update(sibling_nodes)
 
     all_edges = []
     all_edges.extend(skill_edges)
     all_edges.extend(adr_edges)
+    all_edges.extend(service_edges)
+    all_edges.extend(sibling_edges)
 
     # Merge with existing graph (preserving manual entries)
     graph = merge_graph(existing, all_nodes, all_edges)
@@ -280,6 +409,7 @@ def main():
     save_graph(root, graph)
 
     # Report
+    repo_count = len(service_nodes) + len(sibling_nodes)
     output_json({
         "success": True,
         "path": str(graph_path_for_report(root)),
@@ -287,6 +417,7 @@ def main():
         "edges": len(graph["edges"]),
         "skills": len(skill_nodes),
         "decisions": len(adr_nodes),
+        "repos": repo_count,
     })
 
 

package/template/.claude/skills/{flydocs-context-graph → flydocs-workflow}/scripts/graph_query.py

@@ -5,7 +5,7 @@ Returns related nodes for a given starting node, filtered by depth and
 relationship type. Output as compressed markdown or JSON.
 
 Usage:
-    python3 .claude/skills/flydocs-context-graph/scripts/graph_query.py \\
+    python3 .claude/skills/flydocs-workflow/scripts/graph_query.py \\
         --node decision:001 [--depth 2] [--rel EXTENDS] [--reverse] [--format md|json]
 """
 
@@ -91,6 +91,7 @@ def format_markdown(graph, start_node, results):
 
     # Type display order
     type_labels = {
+        "repo": "Repos",
         "decision": "Decisions",
         "skill": "Skills",
         "module": "Modules",
@@ -99,7 +100,7 @@ def format_markdown(graph, start_node, results):
         "concept": "Concepts",
     }
 
-    for node_type in ["decision", "skill", "module", "issue", "session", "concept"]:
+    for node_type in ["repo", "decision", "skill", "module", "issue", "session", "concept"]:
         entries = by_type.get(node_type, [])
         if not entries:
             continue
@@ -109,9 +110,21 @@ def format_markdown(graph, start_node, results):
 
         for node_id, node, rel, depth in entries:
             node_label = node.get("label", node_id)
-            status = node.get("status", "")
-            status_str = f" [{status}]" if status else ""
-            lines.append(f"- {node_id}: {node_label} ({rel}){status_str}")
+            # Repo nodes show purpose; others show status
+            if node_type == "repo":
+                purpose = node.get("purpose", "")
+                extra = f" — {purpose}" if purpose else ""
+                iface = ""
+                # Check if the edge that reached this node has interface info
+                for e in graph.get("edges", []):
+                    if (e.get("from") == node_id or e.get("to") == node_id) and e.get("interface"):
+                        iface = f" via {e['interface']}"
+                        break
+                lines.append(f"- {node_id}: {node_label} ({rel}){iface}{extra}")
+            else:
+                status = node.get("status", "")
+                status_str = f" [{status}]" if status else ""
+                lines.append(f"- {node_id}: {node_label} ({rel}){status_str}")
 
         lines.append("")
 

package/template/.claude/skills/{flydocs-context-graph → flydocs-workflow}/scripts/graph_session.py

@@ -6,7 +6,7 @@ worked on and decisions produced. Supports cross-session continuity by
 building the temporal layer that graph_context.py traverses.
 
 Usage:
-    python3 .claude/skills/flydocs-context-graph/scripts/graph_session.py \
+    python3 .claude/skills/flydocs-workflow/scripts/graph_session.py \
         --summary "Completed Phase 1, started Phase 2" \
         [--issue FLY-56] [--issue FLY-174] \
         [--decision 006] \
@@ -35,15 +35,6 @@ from graph_utils import (
 DEFAULT_RETENTION_DAYS = 30
 
 
-def generate_session_id(session_date):
-    """Generate a session ID like session:2026-02-17-a.
-
-    If a session with the same date exists, increment the sequence letter.
-    """
-    base = f"session:{session_date}"
-    return base
-
-
 def find_next_session_id(graph, session_date):
     """Find the next available session ID for a given date."""
     nodes = graph.get("nodes", {})

package/template/.claude/skills/{flydocs-context-graph → flydocs-workflow}/scripts/graph_update.py

@@ -2,16 +2,16 @@
 """Incrementally add or remove nodes and edges in the context graph.
 
 Usage:
-    python3 .claude/skills/flydocs-context-graph/scripts/graph_update.py \\
+    python3 .claude/skills/flydocs-workflow/scripts/graph_update.py \\
         add-node <ID> --type <TYPE> [--label STR] [--path STR]
 
-    python3 .claude/skills/flydocs-context-graph/scripts/graph_update.py \\
+    python3 .claude/skills/flydocs-workflow/scripts/graph_update.py \\
         remove-node <ID>
 
-    python3 .claude/skills/flydocs-context-graph/scripts/graph_update.py \\
+    python3 .claude/skills/flydocs-workflow/scripts/graph_update.py \\
         add-edge <FROM> <TO> <REL> [--weight N] [--manual]
 
-    python3 .claude/skills/flydocs-context-graph/scripts/graph_update.py \\
+    python3 .claude/skills/flydocs-workflow/scripts/graph_update.py \\
         remove-edge <FROM> <TO> <REL>
 """
 

package/template/.claude/skills/{flydocs-context-graph → flydocs-workflow}/scripts/graph_utils.py

@@ -11,10 +11,11 @@ from pathlib import Path
 
 GRAPH_REL_PATH = os.path.join("flydocs", "context", "graph.json")
 
-VALID_NODE_TYPES = {"skill", "decision", "issue", "module", "session", "concept"}
+VALID_NODE_TYPES = {"skill", "decision", "issue", "module", "session", "concept", "repo"}
 VALID_REL_TYPES = {
     "EXTENDS", "IMPLEMENTS", "DELEGATES_TO", "PRECEDES", "MODIFIES",
     "WORKED_ON", "PRODUCED", "RELATES_TO", "SUPERSEDES", "BLOCKS",
+    "PROVIDES", "CONSUMES",
 }