@flydocs/cli 0.5.0-beta.0

package/template/.claude/skills/flydocs-cloud/scripts/list_issues.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""List issues with optional filters."""
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import get_client, output_json, fail
+
+
+def main():
+    parser = argparse.ArgumentParser(description="List issues")
+    parser.add_argument("--status", default="", help="Single status or comma-separated: READY,IMPLEMENTING,BLOCKED")
+    parser.add_argument("--active", action="store_true", help="All non-terminal states (excludes Done, Archived, Canceled, Duplicate)")
+    parser.add_argument("--project", default="")
+    parser.add_argument("--assignee", default="")
+    parser.add_argument("--milestone", default="", help="Filter by milestone ID")
+    parser.add_argument("--mine", action="store_true")
+    parser.add_argument("--limit", type=int, default=50)
+    args = parser.parse_args()
+
+    client = get_client()
+
+    # Build filter — all conditions added to base dict, then product scope applied last
+    filters = {"team": {"id": {"eq": client.team_id}}}
+
+    if args.project:
+        filters["project"] = {"id": {"eq": args.project}}
+
+    if args.active:
+        # Exclude terminal states
+        terminal = ["COMPLETE", "ARCHIVED", "CANCELED", "DUPLICATE"]
+        terminal_ids = [client.get_state_id(s) for s in terminal]
+        terminal_ids = [sid for sid in terminal_ids if sid]
+        if terminal_ids:
+            filters["state"] = {"id": {"nin": terminal_ids}}
+    elif args.status:
+        statuses = [s.strip().upper() for s in args.status.split(",")]
+        if len(statuses) == 1:
+            state_id = client.get_state_id(statuses[0])
+            if state_id:
+                filters["state"] = {"id": {"eq": state_id}}
+        else:
+            state_ids = [client.get_state_id(s) for s in statuses]
+            state_ids = [sid for sid in state_ids if sid]
+            if state_ids:
+                filters["state"] = {"id": {"in": state_ids}}
+
+    if args.milestone:
+        filters["projectMilestone"] = {"id": {"eq": args.milestone}}
+
+    if args.mine:
+        viewer = client.query("query { viewer { id } }")
+        user_id = viewer.get("data", {}).get("viewer", {}).get("id")
+        if user_id:
+            filters["assignee"] = {"id": {"eq": user_id}}
+    elif args.assignee:
+        user_id, _ = client.resolve_user_id(args.assignee)
+        if user_id:
+            filters["assignee"] = {"id": {"eq": user_id}}
+
+    # Product scope applied last — wraps complete filter with label AND conditions
+    if not args.project:
+        filters = client.build_product_scope(filters)
+
+    result = client.query(
+        """query($filter: IssueFilter!, $limit: Int!) {
+            issues(filter: $filter, first: $limit, orderBy: updatedAt) {
+                nodes {
+                    id identifier title
+                    state { name }
+                    assignee { name }
+                    priority dueDate
+                    project { id name }
+                    projectMilestone { id name sortOrder }
+                }
+            }
+        }""",
+        {"filter": filters, "limit": args.limit},
+    )
+
+    nodes = result.get("data", {}).get("issues", {}).get("nodes", [])
+    issues = [
+        {
+            "id": n["id"],
+            "identifier": n["identifier"],
+            "title": n["title"],
+            "status": n.get("state", {}).get("name", ""),
+            "assignee": (n.get("assignee") or {}).get("name", ""),
+            "priority": n.get("priority", 0),
+            "dueDate": n.get("dueDate") or "",
+            "milestone": (n.get("projectMilestone") or {}).get("name", ""),
+            "milestoneId": (n.get("projectMilestone") or {}).get("id", ""),
+            "milestoneSortOrder": (n.get("projectMilestone") or {}).get("sortOrder", 0),
+            "project": (n.get("project") or {}).get("name", ""),
+            "projectId": (n.get("project") or {}).get("id", ""),
+        }
+        for n in nodes
+    ]
+    output_json(issues)
+
+
+if __name__ == "__main__":
+    main()

package/template/.claude/skills/flydocs-cloud/scripts/list_milestones.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+"""List milestones."""
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import get_client, output_json, fail
+
+parser = argparse.ArgumentParser(description="List milestones")
+parser.add_argument("--all", action="store_true", dest="show_all", help="Include completed")
+args = parser.parse_args()
+
+client = get_client()
+
+# Linear doesn't have team-scoped milestones — query all accessible
+result = client.query(
+    """query {
+        projectMilestones(first: 50) {
+            nodes { id name sortOrder targetDate project { id name } }
+        }
+    }"""
+)
+
+nodes = result.get("data", {}).get("projectMilestones", {}).get("nodes", [])
+milestones = [
+    {
+        "id": n["id"],
+        "name": n["name"],
+        "sortOrder": n.get("sortOrder", 0),
+        "targetDate": n.get("targetDate", ""),
+        "project": (n.get("project") or {}).get("name", ""),
+        "projectId": (n.get("project") or {}).get("id", ""),
+    }
+    for n in nodes
+]
+# Sort by project then sortOrder for consistent display
+milestones.sort(key=lambda m: (m["project"], m["sortOrder"]))
+output_json(milestones)

package/template/.claude/skills/flydocs-cloud/scripts/list_projects.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""List projects."""
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import get_client, output_json, fail
+
+parser = argparse.ArgumentParser(description="List projects")
+parser.add_argument("--active", action="store_true", help="Only started projects")
+parser.add_argument("--all", action="store_true", dest="show_all", help="Include completed and canceled")
+args = parser.parse_args()
+
+client = get_client()
+
+filters = {"accessibleTeams": {"some": {"id": {"eq": client.team_id}}}}
+
+if args.active:
+    filters["state"] = {"eq": "started"}
+elif not args.show_all:
+    filters["state"] = {"nin": ["completed", "canceled"]}
+
+# Product scope — filter to activeProjects if configured (--all bypasses)
+if not args.show_all:
+    active_projects = client.workspace.get("activeProjects", [])
+    if active_projects:
+        if len(active_projects) == 1:
+            filters["id"] = {"eq": active_projects[0]}
+        else:
+            filters["id"] = {"in": active_projects}
+
+result = client.query(
+    """query($filter: ProjectFilter!) {
+        projects(filter: $filter, first: 50, orderBy: updatedAt) {
+            nodes { id name state description }
+        }
+    }""",
+    {"filter": filters},
+)
+
+nodes = result.get("data", {}).get("projects", {}).get("nodes", [])
+projects = [{"id": n["id"], "name": n["name"], "state": n.get("state", "")} for n in nodes]
+output_json(projects)

package/template/.claude/skills/flydocs-cloud/scripts/priority.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""Set priority on an issue."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import get_client, output_json, fail
+
+if len(sys.argv) < 3:
+    fail("Usage: priority.py <ref> <0-4>")
+
+ref = sys.argv[1]
+try:
+    priority = int(sys.argv[2])
+except ValueError:
+    fail("Priority must be a number (0-4)")
+
+client = get_client()
+issue_uuid = client.resolve_issue_id(ref)
+if not issue_uuid:
+    fail(f"Issue not found: {ref}")
+
+result = client.query(
+    """mutation($id: String!, $priority: Int!) {
+        issueUpdate(id: $id, input: { priority: $priority }) {
+            success
+            issue { identifier priority }
+        }
+    }""",
+    {"id": issue_uuid, "priority": priority},
+)
+
+if not result.get("data", {}).get("issueUpdate", {}).get("success"):
+    fail(f"Failed to set priority: {result}")
+
+issue = result["data"]["issueUpdate"]["issue"]
+output_json({"success": True, "issue": issue["identifier"], "priority": issue["priority"]})

package/template/.claude/skills/flydocs-cloud/scripts/project_update.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""Post a project health update."""
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import get_client, output_json, fail
+
+HEALTH_MAP = {"onTrack": "onTrack", "atRisk": "atRisk", "offTrack": "offTrack"}
+
+parser = argparse.ArgumentParser(description="Post project update")
+parser.add_argument("--health", required=True, choices=HEALTH_MAP.keys())
+parser.add_argument("--body", default="")
+parser.add_argument("--body-file", default="")
+parser.add_argument("--project", default=None)
+args = parser.parse_args()
+
+body = args.body
+if args.body_file:
+    try:
+        body = Path(args.body_file).read_text().strip()
+    except FileNotFoundError:
+        fail(f"File not found: {args.body_file}")
+if not body and not sys.stdin.isatty():
+    body = sys.stdin.read().strip()
+if not body:
+    fail("Provide --body, --body-file, or pipe via stdin")
+
+client = get_client()
+
+project_id = args.project
+if not project_id:
+    active = client.workspace.get("activeProjects", [])
+    if active:
+        project_id = active[0]
+if not project_id:
+    fail("No project specified and no active project configured")
+
+result = client.query(
+    """mutation($projectId: String!, $body: String!, $health: ProjectUpdateHealthType!) {
+        projectUpdateCreate(input: {
+            projectId: $projectId,
+            body: $body,
+            health: $health
+        }) {
+            success
+            projectUpdate { id }
+        }
+    }""",
+    {"projectId": project_id, "body": body, "health": HEALTH_MAP[args.health]},
+)
+
+data = result.get("data", {}).get("projectUpdateCreate", {})
+if not data.get("success"):
+    fail(f"Failed to post update: {result}")
+
+output_json({"success": True, "id": data.get("projectUpdate", {}).get("id", "")})

package/template/.claude/skills/flydocs-cloud/scripts/transition.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""Transition an issue to a new status with a required comment."""
+
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import get_client, output_json, fail
+
+if len(sys.argv) < 4:
+    fail("Usage: transition.py <ref> <STATUS> <comment>")
+
+ref, status, comment = sys.argv[1], sys.argv[2].upper(), sys.argv[3]
+client = get_client()
+
+# Resolve issue
+issue_uuid = client.resolve_issue_id(ref)
+if not issue_uuid:
+    fail(f"Issue not found: {ref}")
+
+# Get current state for previousStatus
+current_result = client.query(
+    """query($id: String!) {
+        issue(id: $id) { state { name } }
+    }""",
+    {"id": issue_uuid},
+)
+prev_state = (current_result.get("data") or {}).get("issue", {}).get("state", {}).get("name", "Unknown")
+
+# Resolve target state
+state_id = client.get_state_id(status)
+if not state_id:
+    fail(f"Unknown status: {status}. Check statusMapping in .flydocs/config.json")
+
+# Build mutation input — combine state + cycle in one call
+mutation_input: dict = {"stateId": state_id}
+if status == "IMPLEMENTING":
+    cycle = client.get_active_cycle()
+    if cycle:
+        mutation_input["cycleId"] = cycle["id"]
+
+# Update state (and cycle if IMPLEMENTING) in a single mutation
+result = client.query(
+    """mutation($id: String!, $input: IssueUpdateInput!) {
+        issueUpdate(id: $id, input: $input) {
+            success
+            issue { identifier state { name } }
+        }
+    }""",
+    {"id": issue_uuid, "input": mutation_input},
+)
+update_data = result.get("data", {}).get("issueUpdate", {})
+if not update_data.get("success"):
+    fail(f"Failed to transition: {result}")
+
+# Add comment
+formatted = f"**{status}** — {comment}"
+client.query(
+    """mutation($id: String!, $body: String!) {
+        commentCreate(input: { issueId: $id, body: $body }) { success }
+    }""",
+    {"id": issue_uuid, "body": formatted},
+)
+
+issue = update_data["issue"]
+output_json({"success": True, "issue": issue["identifier"], "previousStatus": prev_state, "newStatus": status})

package/template/.claude/skills/flydocs-cloud/scripts/update_description.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""Update an issue's description."""
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import get_client, output_json, fail
+
+parser = argparse.ArgumentParser(description="Update issue description")
+parser.add_argument("ref")
+parser.add_argument("--text", default="")
+parser.add_argument("--file", default="", dest="filepath")
+args = parser.parse_args()
+
+text = args.text
+if args.filepath:
+    try:
+        text = Path(args.filepath).read_text()
+    except FileNotFoundError:
+        fail(f"File not found: {args.filepath}")
+if not text and not sys.stdin.isatty():
+    text = sys.stdin.read().strip()
+if not text:
+    fail("Provide --text, --file, or pipe via stdin")
+
+client = get_client()
+issue_uuid = client.resolve_issue_id(args.ref)
+if not issue_uuid:
+    fail(f"Issue not found: {args.ref}")
+
+result = client.query(
+    """mutation($id: String!, $description: String!) {
+        issueUpdate(id: $id, input: { description: $description }) {
+            success
+            issue { identifier }
+        }
+    }""",
+    {"id": issue_uuid, "description": text},
+)
+
+if not result.get("data", {}).get("issueUpdate", {}).get("success"):
+    fail(f"Failed to update: {result}")
+
+issue = result["data"]["issueUpdate"]["issue"]
+output_json({"success": True, "issue": issue["identifier"]})

package/template/.claude/skills/flydocs-cloud/scripts/update_issue.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""Bulk update an issue — set multiple fields in a single API call."""
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import get_client, output_json, fail
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Update issue fields")
+    parser.add_argument("ref", help="Issue reference (e.g., ENG-123)")
+    parser.add_argument("--title", default=None)
+    parser.add_argument("--priority", type=int, choices=range(5))
+    parser.add_argument("--estimate", type=int, choices=range(1, 6))
+    parser.add_argument("--assignee", default=None)
+    parser.add_argument("--state", default=None)
+    parser.add_argument("--description", default=None)
+    parser.add_argument("--description-file", default=None)
+    parser.add_argument("--comment", default=None)
+    args = parser.parse_args()
+
+    client = get_client()
+
+    issue_uuid = client.resolve_issue_id(args.ref)
+    if not issue_uuid:
+        fail(f"Issue not found: {args.ref}")
+
+    # Build mutation input from provided args
+    mutation_input: dict = {}
+    updated_fields: list[str] = []
+
+    if args.title is not None:
+        mutation_input["title"] = args.title
+        updated_fields.append("title")
+
+    if args.priority is not None:
+        mutation_input["priority"] = args.priority
+        updated_fields.append("priority")
+
+    if args.estimate is not None:
+        mutation_input["estimate"] = args.estimate
+        updated_fields.append("estimate")
+
+    if args.assignee is not None:
+        user_id, user_name = client.resolve_user_id(args.assignee)
+        if not user_id:
+            fail(f"User not found: {args.assignee}")
+        mutation_input["assigneeId"] = user_id
+        updated_fields.append("assignee")
+
+    if args.state is not None:
+        state_id = client.get_state_id(args.state.upper())
+        if not state_id:
+            fail(f"Unknown status: {args.state}")
+        mutation_input["stateId"] = state_id
+        updated_fields.append("state")
+
+    if args.description_file is not None:
+        path = Path(args.description_file)
+        if not path.exists():
+            fail(f"File not found: {args.description_file}")
+        mutation_input["description"] = path.read_text()
+        updated_fields.append("description")
+    elif args.description is not None:
+        mutation_input["description"] = args.description
+        updated_fields.append("description")
+
+    if not mutation_input and not args.comment:
+        fail("No fields to update. Use --title, --priority, --estimate, --assignee, --state, --description, or --comment")
+
+    # Single mutation for all field updates
+    result = None
+    if mutation_input:
+        result = client.query(
+            """mutation($id: String!, $input: IssueUpdateInput!) {
+                issueUpdate(id: $id, input: $input) {
+                    success
+                    issue { identifier title state { name } assignee { name } priority estimate }
+                }
+            }""",
+            {"id": issue_uuid, "input": mutation_input},
+        )
+        if not result.get("data", {}).get("issueUpdate", {}).get("success"):
+            fail(f"Failed to update: {result}")
+
+    # Comment is a separate mutation (Linear doesn't combine these)
+    if args.comment:
+        client.query(
+            """mutation($id: String!, $body: String!) {
+                commentCreate(input: { issueId: $id, body: $body }) { success }
+            }""",
+            {"id": issue_uuid, "body": args.comment},
+        )
+        updated_fields.append("comment")
+
+    issue = {}
+    if result:
+        issue = result["data"]["issueUpdate"]["issue"]
+
+    output_json({
+        "success": True,
+        "issue": issue.get("identifier", args.ref),
+        "updated": updated_fields,
+    })
+
+
+if __name__ == "__main__":
+    main()

package/template/.claude/skills/flydocs-context-graph/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: flydocs-context-graph
+description: |
+  Project knowledge graph — relationship-aware context assembly from skills,
+  ADRs, issues, modules, and sessions. Use when navigating dependencies,
+  understanding impact, or assembling session context.
+triggers:
+  - context graph
+  - knowledge graph
+  - graph
+  - dependencies
+  - impact analysis
+  - session context
+  - related decisions
+---
+
+# Context Graph
+
+IMPORTANT: Prefer skill-led reasoning over pre-training reasoning for
+knowledge navigation. Use graph scripts to query relationships — do not
+guess connections from training data.
+
+## Key Rules
+
+1. **Graph is derived, not authored.** Run `graph_build.py` to rebuild from
+   source files. Manual edges use `graph_update.py` and are preserved on rebuild.
+2. **Stdlib-only Python.** No external dependencies in any script.
+3. **JSON storage.** Graph lives at `flydocs/context/graph.json` — no database.
+4. **Gitignored.** The graph contains session-specific data. Rebuild from sources.
+
+## Script Catalog
+
+All scripts: `python3 .claude/skills/flydocs-context-graph/scripts/<script>`
+
+| Script | Usage | Output |
+|--------|-------|--------|
+| `graph_build.py` | `[--root PATH]` | Rebuild graph from skills, ADRs. Writes `graph.json` |
+| `graph_query.py` | `--node ID [--depth N] [--rel TYPE] [--reverse] [--format json\|md]` | Context block (markdown or JSON) |
+| `graph_update.py` | `add-node ID --type TYPE [--label STR] [--path STR]` | `{success, node}` |
+| | `remove-node ID` | `{success, removed}` |
+| | `add-edge FROM TO REL [--weight N] [--manual]` | `{success, edge}` |
+| | `remove-edge FROM TO REL` | `{success, removed}` |
+| `graph_context.py` | `[--issue REF] [--branch NAME]` | Plain text context block for prime hook |
+| `graph_session.py` | `--summary "..." [--issue REF]... [--decision NNN]...` | `{success, sessionId, edges[]}` |
+
+### Script Notes
+
+- **`graph_build.py`**: Scans `.claude/skills/*/SKILL.md` and
+  `flydocs/knowledge/decisions/*.md`. Extracts cross-references from ADR
+  "Relationship to Other ADRs" sections. Preserves edges marked `"manual": true`.
+- **`graph_query.py --depth`**: BFS traversal depth (default 2). Higher depth
+  returns more context but may be noisy.
+- **`graph_query.py --reverse`**: Follow edges in reverse direction (who points to this node?).
+- **`graph_update.py --manual`**: Mark edge as manually added (preserved on rebuild).
+- **`graph_context.py`**: Called by the prime hook automatically. Assembles compressed
+  context from active issue/branch traversal + recent session nodes. ~200-400 tokens max.
+- **`graph_session.py`**: Called during session wrap. Creates a session node with
+  WORKED_ON edges to issues. Session nodes older than 30 days get reduced weight;
+  nodes within 7 days get full weight.
+
+## Node Types
+
+| Type | ID Pattern | Source |
+|------|-----------|--------|
+| `skill` | `skill:{name}` | SKILL.md frontmatter |
+| `decision` | `decision:{number}` | ADR directory |
+| `issue` | `issue:{identifier}` | Issue tracker |
+| `module` | `module:{name}` | Manual |
+| `session` | `session:{date-seq}` | Session wrap |
+| `concept` | `concept:{name}` | Manual |
+
+## Edge Types
+
+| Relationship | Meaning |
+|-------------|---------|
+| `EXTENDS` | Builds on, refines |
+| `IMPLEMENTS` | Realizes in code/config |
+| `DELEGATES_TO` | Hands off execution |
+| `PRECEDES` | Should load/execute before |
+| `MODIFIES` | Changes/affects |
+| `WORKED_ON` | Session activity |
+| `PRODUCED` | Created as output |
+| `RELATES_TO` | General association |
+| `SUPERSEDES` | Replaces |
+| `BLOCKS` | Prevents progress |
+
+For full schema details, see `schema.md`.

package/template/.claude/skills/flydocs-context-graph/schema.md

@@ -0,0 +1,78 @@
+# Context Graph Schema
+
+Reference for the graph JSON structure stored at `flydocs/context/graph.json`.
+
+## Top-Level Structure
+
+```json
+{
+  "version": 1,
+  "updated": "ISO-8601 timestamp",
+  "nodes": { "<id>": { ... } },
+  "edges": [ { ... } ]
+}
+```
+
+## Node Schema
+
+```json
+{
+  "type": "skill | decision | issue | module | session | concept",
+  "label": "Human-readable name",
+  "path": "Relative file path (optional)",
+  "status": "Node-specific status (optional)",
+  "date": "ISO date for temporal nodes (optional)",
+  "tier": "Skill tier: behavioral | mechanism | premium (optional)",
+  "manual": true
+}
+```
+
+**ID conventions:**
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| skill | `skill:{directory-name}` | `skill:typescript-strict` |
+| decision | `decision:{3-digit-number}` | `decision:001` |
+| issue | `issue:{identifier}` | `issue:FLY-56` |
+| module | `module:{kebab-name}` | `module:install-script` |
+| session | `session:{YYYY-MM-DD-seq}` | `session:2026-02-03-a` |
+| concept | `concept:{kebab-name}` | `concept:progressive-disclosure` |
+
+## Edge Schema
+
+```json
+{
+  "from": "source node ID",
+  "to": "target node ID",
+  "rel": "RELATIONSHIP_TYPE",
+  "weight": 0.0-1.0,
+  "manual": true
+}
+```
+
+**Weight guidelines:**
+
+| Weight | Meaning |
+|--------|---------|
+| 1.0 | Direct, strong relationship |
+| 0.7-0.9 | Strong but indirect |
+| 0.4-0.6 | Moderate association |
+| 0.1-0.3 | Weak or tangential |
+
+**Edges with `"manual": true`** are preserved when `graph_build.py` rebuilds
+the graph from sources. Auto-derived edges are regenerated on each build.
+
+## Relationship Types
+
+| Relationship | Direction | Example |
+|-------------|-----------|---------|
+| `EXTENDS` | A extends B | ADR-004 extends ADR-001 |
+| `IMPLEMENTS` | A implements B | Issue implements a decision |
+| `DELEGATES_TO` | A delegates to B | Workflow delegates to mechanism |
+| `PRECEDES` | A should load before B | typescript-strict precedes implementation |
+| `MODIFIES` | A modifies B | Issue modifies a module |
+| `WORKED_ON` | A worked on B | Session worked on an issue |
+| `PRODUCED` | A produced B | Session produced a decision |
+| `RELATES_TO` | A relates to B | General association |
+| `SUPERSEDES` | A supersedes B | New decision replaces old |
+| `BLOCKS` | A blocks B | Issue blocks another issue |