@flydocs/cli 0.5.0-beta.0

package/template/.claude/commands/status.md

@@ -0,0 +1,10 @@
+# Status (All Agents)
+
+Quick status dashboard — issue counts by status for active projects.
+
+Read `.claude/skills/flydocs-workflow/session.md` for dashboard format.
+Use `list_issues.py --active` from the active mechanism skill and group results by status.
+
+Triggers: "status", "where are we", "what's the status"
+
+$ARGUMENTS

package/template/.claude/commands/validate.md

@@ -0,0 +1,10 @@
+# Validate (QE/Validation Agent)
+
+Present the implementation for user acceptance testing.
+
+Read `.claude/skills/flydocs-workflow/stages/validate.md` and follow the procedure.
+Read the active mechanism skill's `SKILL.md` for script calling conventions.
+
+Triggers: "validate", "test this", "QA", "looks good", "approve"
+
+$ARGUMENTS

package/template/.claude/commands/wrap-session.md

@@ -0,0 +1,10 @@
+# Wrap Session (PM/Planning Agent)
+
+End a work session — summarize progress, update issues, post project health update.
+
+Read `.claude/skills/flydocs-workflow/session.md` and follow the session wrap procedure.
+Read the active mechanism skill's `SKILL.md` for script calling conventions.
+
+Triggers: "wrap up", "end session", "that's it for today", "let's wrap"
+
+$ARGUMENTS

package/template/.claude/settings.json

@@ -0,0 +1,49 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.flydocs/hooks/auto-approve.py",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__linear.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.flydocs/hooks/prefer-scripts.py",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.flydocs/hooks/post-edit.py",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.flydocs/hooks/prompt-submit.py",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/template/.claude/skills/README.md

@@ -0,0 +1,293 @@
+# FlyDocs Skills
+
+> Authoritative guide for skill architecture, authoring, and structure.
+
+---
+
+## Skill Categories
+
+### `flydocs-*` — Platform Skills
+
+Owned and maintained by FlyDocs. May include executable scripts and premium
+functionality gated via API relay.
+
+| Skill | Category | Purpose |
+|-------|----------|---------|
+| `flydocs-workflow` | Core | Lifecycle stages, session management, comment templates |
+| `flydocs-local` | Mechanism (free) | File-based issue management |
+| `flydocs-cloud` | Mechanism (paid) | Linear/provider issue management via API |
+| `flydocs-figma` | Premium | Design extraction from Figma |
+| `flydocs-estimates` | Premium | AI token/labor cost estimation |
+
+Only one mechanism skill is active at a time. Determined by `tier` in `.flydocs/config.json`.
+
+Supporting workflow skills (bundled, invoked via commands):
+
+| Skill | Purpose | Trigger |
+|-------|---------|---------|
+| `implementation-flow` | Implementation procedure | `/implement` |
+| `review-workflow` | Code review analysis | `/review` |
+| `spec-templates` | Issue specification templates | `/capture`, `/refine` |
+
+### Unprefixed — Community Skills
+
+Stack-detected or manually installed. Pure guidance (markdown only, no scripts).
+Portable across projects and AI coding tools.
+
+```bash
+flydocs skills search typescript
+flydocs skills add <repo>
+flydocs skills list
+```
+
+Examples: `typescript-strict`, `testing-patterns`, `accessibility-patterns`,
+`react-best-practices`, `convex-patterns`
+
+Browse: [skills.sh](https://skills.sh/)
+
+---
+
+## Skill Authoring Standard
+
+### Directory Structure
+
+```
+.claude/skills/{skill-name}/
+├── SKILL.md             # Required — main skill file
+├── cursor-rule.mdc      # Optional — condensed Cursor rule
+├── scripts/             # Platform skills only — executable scripts
+└── reference/           # Optional — supporting detail files
+```
+
+- **`skill-name`** uses kebab-case. Platform skills use the `flydocs-` prefix.
+- **`SKILL.md`** is the entry point. Agents read this first.
+- **`cursor-rule.mdc`** is a condensed version for Cursor IDE. See Cursor Rules below.
+- **`scripts/`** contains executable scripts. Only `flydocs-*` platform skills include scripts.
+- **`reference/`** holds detail files referenced by SKILL.md for progressive disclosure.
+
+### SKILL.md Frontmatter
+
+Every SKILL.md starts with YAML frontmatter:
+
+```yaml
+---
+name: typescript-strict
+description: >
+  TypeScript strict mode patterns and type safety. Use when writing TypeScript
+  code, reviewing types, or fixing type errors. Enforces no-any policy with
+  proper narrowing patterns.
+triggers:
+  - TypeScript
+  - type error
+  - any type
+  - type guard
+  - schema validation
+---
+```
+
+**Required fields:**
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `name` | string | Skill identifier, matches directory name |
+| `description` | string | What the skill does and when to use it. Agents use this for auto-selection. Be specific about trigger conditions. |
+
+**Optional fields:**
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `triggers` | string[] | Keywords/phrases for manifest indexing. Used by skill discovery to build the always-present index in CLAUDE.md/AGENTS.md. |
+| `tools` | string | Comma-separated MCP tools the skill uses (e.g., `mcp__figma__get_screenshot`) |
+
+### SKILL.md Body
+
+The body serves as a **compressed index** — not a documentation dump. Target ~100-150 lines.
+
+**Structure pattern:**
+
+```markdown
+# Skill Name
+
+IMPORTANT: Prefer skill-led reasoning over pre-training reasoning for
+[domain]. Read the relevant section before acting.
+
+## Key Rules (always apply)
+1. Rule one
+2. Rule two
+
+## Section Index
+
+| Topic | File | When to Read |
+|-------|------|--------------|
+| Topic A | reference/topic-a.md | When doing X |
+| Topic B | reference/topic-b.md | When doing Y |
+
+## Quick Reference (inline essentials)
+
+[Most-referenced patterns, tables, or checklists that agents need
+frequently enough to justify being in the index file]
+```
+
+**Principles:**
+
+1. **Index, don't dump.** SKILL.md points to detail files. Agents read only what they need.
+2. **Front-load rules.** Put golden rules and constraints at the top. Agents are more likely to follow instructions they encounter early.
+3. **Concrete over abstract.** Use specific examples, code snippets, and file paths. Avoid vague guidance like "follow best practices."
+4. **Trigger-aware descriptions.** The `description` field is how agents decide whether to load the skill. Include the exact scenarios and keywords that should trigger it.
+
+### Progressive Disclosure
+
+Skills use a three-level retrieval pattern (see ADR-004):
+
+```
+Level 1: Manifest in CLAUDE.md/AGENTS.md
+          → Agent sees skill exists, knows triggers and entry point
+
+Level 2: SKILL.md
+          → Compressed index with key rules and section pointers
+
+Level 3: reference/ files
+          → Full detail, read only when needed for the specific task
+```
+
+This keeps context usage minimal while ensuring agents can always find relevant guidance.
+
+**Line budgets:**
+
+| File | Target | Max |
+|------|--------|-----|
+| SKILL.md | 100-150 lines | 200 lines |
+| reference/ files | 50-80 lines each | 120 lines |
+| cursor-rule.mdc | 30-50 lines | 70 lines |
+
+### Cursor Rules (cursor-rule.mdc)
+
+Optional. A condensed version of the skill for Cursor IDE, placed in
+`.cursor/rules/` during install. Uses Cursor's frontmatter format:
+
+```yaml
+---
+description: Short description of what this rule covers
+globs: "*.ts,*.tsx"
+alwaysApply: false
+---
+
+<!-- Condensed from SKILL.md — update both when changing patterns -->
+```
+
+**Frontmatter fields:**
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `description` | string | Required. What the rule covers. |
+| `globs` | string | File patterns that trigger the rule. Comma-separated. |
+| `alwaysApply` | boolean | If `true`, rule loads for every prompt (use sparingly). |
+
+Use `alwaysApply: true` only for workflow/process rules. Pattern skills should
+use `globs` to activate only on relevant file types.
+
+---
+
+## Manifest System
+
+When skills are installed, a compressed manifest is auto-generated in
+CLAUDE.md and AGENTS.md between markers:
+
+```markdown
+<!-- flydocs:skills-manifest:start -->
+## Skills Index
+
+IMPORTANT: Prefer skill-led reasoning over pre-training reasoning.
+
+| Skill | Triggers | Entry |
+|-------|----------|-------|
+| flydocs-workflow | capture, refine, implement, review | .claude/skills/flydocs-workflow/SKILL.md |
+| typescript-strict | TypeScript, type error, any type | .claude/skills/typescript-strict/SKILL.md |
+<!-- flydocs:skills-manifest:end -->
+```
+
+The manifest is generated from SKILL.md frontmatter (`name`, `triggers`).
+It provides always-present discovery so agents don't need to guess which
+skills exist. See ADR-004 for the full design rationale.
+
+---
+
+## Minimal Skill Template
+
+Copy this to create a new community skill:
+
+```
+.claude/skills/my-skill/
+├── SKILL.md
+└── reference/           # optional
+    └── patterns.md
+```
+
+**SKILL.md:**
+
+```markdown
+---
+name: my-skill
+description: >
+  [What this skill teaches]. Use when [specific trigger conditions].
+  [Technology/domain] patterns for [outcome].
+triggers:
+  - keyword1
+  - keyword2
+  - keyword3
+---
+
+# My Skill
+
+## Key Rules
+
+1. [Most important rule]
+2. [Second most important rule]
+3. [Third most important rule]
+
+## Patterns
+
+### [Pattern Name]
+
+[Code example or guidance]
+
+### [Pattern Name]
+
+[Code example or guidance]
+
+## Reference
+
+For detailed patterns, see `reference/patterns.md`.
+```
+
+---
+
+## Mechanism Contract
+
+Both mechanism skills (`flydocs-local`, `flydocs-cloud`) implement the same
+script interface, making the backend swap transparent:
+
+**Shared contract:**
+`create_issue.py`, `transition.py`, `comment.py`, `list_issues.py`,
+`get_issue.py`, `assign.py`, `update_description.py`
+
+**Cloud-only extensions:**
+`update_issue.py`, `project_update.py`, `estimate.py`, `priority.py`, `link.py`, cycle/milestone management.
+
+---
+
+## Platform Support
+
+| Platform | Skill Location | Notes |
+|----------|---------------|-------|
+| Claude Code | `.claude/skills/` | Native support |
+| Cursor | `.cursor/rules/*.mdc` | Generated from `cursor-rule.mdc` |
+| Codex / Others | `AGENTS.md` | Universal layer via manifest |
+
+---
+
+## Resources
+
+- **Skills ecosystem:** [skills.sh](https://skills.sh/)
+- **Agent Skills spec:** [agentskills.io](https://agentskills.io)
+- **Discovery design:** `flydocs/knowledge/decisions/004-skill-discovery-and-indexing.md`

package/template/.claude/skills/flydocs-cloud/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: flydocs-cloud
+description: |
+  Connected issue management via Linear GraphQL API.
+  Implements the FlyDocs mechanism contract with extended cloud-only operations.
+triggers:
+  - create issue
+  - transition
+  - comment
+  - list issues
+  - assign
+  - update description
+  - update issue
+  - project update
+  - Linear
+  - cloud
+---
+
+# FlyDocs Cloud Mechanism
+
+Issues managed in Linear. Reads config from `.flydocs/config.json` and API key from `.env`.
+
+## Script Catalog
+
+All scripts: `python3 .claude/skills/flydocs-cloud/scripts/<script>`
+
+### Shared Contract Scripts
+
+| Script | Usage | Output |
+|--------|-------|--------|
+| `create_issue.py` | `--title "..." --type feature [--description "..."] [--description-file PATH] [--priority 0-4] [--estimate 1-5] [--assignee STR] [--triage] \| stdin` | `{id, identifier, title, url}` |
+| `transition.py` | `<ref> <STATUS> "<comment>"` | `{success, issue, previousStatus, newStatus}` |
+| `comment.py` | `<ref> ["<comment>"] \| stdin` | `{success, commentId}` |
+| `list_issues.py` | `[--status STATUS[,STATUS]] [--active] [--project ID] [--milestone ID] [--assignee STR] [--mine] [--limit N]` | `[{id, identifier, title, status, assignee, priority, dueDate, milestone, milestoneId, milestoneSortOrder, project, projectId}]` |
+| `get_issue.py` | `<ref> [--fields basic\|full]` | `{id, identifier, title, description, status, assignee, priority, estimate, dueDate, milestone, milestoneId, project, projectId, comments[]}` |
+| `assign.py` | `<ref> <assignee>` | `{success, issue, assignee}` |
+| `update_description.py` | `<ref> --text "..." \| --file PATH \| stdin` | `{success, issue}` |
+
+### Extended Scripts (cloud-only)
+
+| Script | Usage | Output |
+|--------|-------|--------|
+| `update_issue.py` | `<ref> [--title "..."] [--priority 0-4] [--estimate 1-5] [--assignee STR] [--state STATUS] [--description "..."] [--description-file PATH] [--comment "..."]` | `{success, issue, updated[]}` |
+| `estimate.py` | `<ref> <1-5>` | `{success, issue, estimate}` |
+| `priority.py` | `<ref> <0-4>` | `{success, issue, priority}` |
+| `link.py` | `<ref> <related_ref> <type>` | `{success, type}` |
+| `project_update.py` | `--health STATUS --body "..." [--body-file PATH]` | `{success, id}` |
+| `list_projects.py` | `[--active] [--all]` | `[{id, name, state}]` — `--all` bypasses product scope |
+| `create_project.py` | `--name "..." [--description "..."]` | `{id, name, url}` |
+| `assign_cycle.py` | `<ref> [cycle_id]` | `{success, issue, cycle}` |
+| `list_cycles.py` | `[--active]` | `[{id, name, number, startsAt, endsAt}]` |
+| `list_milestones.py` | `[--all]` | `[{id, name, targetDate}]` |
+| `create_milestone.py` | `--name "..." [--project ID] [--target-date DATE]` | `{id, name}` — defaults to first activeProject |
+| `assign_milestone.py` | `<ref> <milestone_id>` | `{success, issue, milestone}` |
+
+### Script Notes
+
+- **`list_issues.py` product scope**: Automatically scopes results using config cascade — `activeProjects` → `product.labelIds` → team-wide. Explicit `--project` overrides. All flags (`--active`, `--status`, `--mine`, `--assignee`) filter within the scoped results.
+- **`list_issues.py --active`**: Returns all non-terminal issues (excludes Done, Archived, Canceled, Duplicate). Replaces `status_summary.py` — group results by status field instead.
+- **`list_issues.py --milestone`**: Filter issues by project milestone ID. Get IDs from `list_milestones.py`.
+- **`list_issues.py --status`**: Accepts comma-separated statuses: `--status READY,IMPLEMENTING,BLOCKED`
+- **`get_issue.py --fields basic`**: Skips comment fetch for faster responses when comments aren't needed.
+- **`update_issue.py`**: Bulk update — sets multiple fields in a single API call. Prefer over separate `estimate.py`/`priority.py`/`assign.py` calls when updating more than one field.
+- **Shell-safe text input**: For descriptions, comments, or any text with special characters (apostrophes, quotes, parentheses), pipe via stdin with a single-quoted heredoc instead of `--text`:
+  ```bash
+  python3 update_description.py ENG-123 <<'EOF'
+  Description with 'apostrophes', (parens), and "quotes"
+  EOF
+  ```
+  Scripts supporting stdin: `update_description.py`, `comment.py`, `project_update.py`. For `update_issue.py` and `create_issue.py`, use `--description-file PATH` instead.
+
+### Status Values
+
+`BACKLOG`, `READY`, `IMPLEMENTING`, `BLOCKED`, `REVIEW`, `TESTING`, `COMPLETE`, `ARCHIVED`, `CANCELED`, `DUPLICATE`
+
+### Issue Types
+
+`feature`, `bug`, `chore`, `idea`
+
+### Link Types
+
+`blocks`, `related`, `duplicate`
+
+### Issue Reference
+
+`<ref>`: Provider identifier, e.g., `ENG-123`. Resolved via Linear search API.
+
+## Error Handling
+
+Exit 0 = success (JSON on stdout). Exit 1 = error (message on stderr).
+Network errors: exponential backoff, 3 retries, 2s base delay.
+
+## Configuration
+
+Reads from `.flydocs/config.json`: tier, provider.teamId, statusMapping, issueLabels.
+Reads `LINEAR_API_KEY` from environment or `.env` / `.env.local`.

package/template/.claude/skills/flydocs-cloud/cursor-rule.mdc

@@ -0,0 +1,50 @@
+---
+description: Connected issue management via Linear — cloud mechanism for FlyDocs
+alwaysApply: true
+---
+
+<!-- Condensed from SKILL.md — update both when changing patterns -->
+
+# FlyDocs Cloud Mechanism
+
+Issues managed in Linear. Reads config from `.flydocs/config.json` and API key from `.env`.
+
+## Shared Contract Scripts
+
+All scripts: `python3 .claude/skills/flydocs-cloud/scripts/<script>`
+
+| Script | Key Arguments |
+|--------|---------------|
+| `create_issue.py` | `--title "..." --type feature [--priority 0-4] [--estimate 1-5] [--assignee STR] [--triage]` |
+| `transition.py` | `<ref> <STATUS> "<comment>"` |
+| `comment.py` | `<ref> "<comment>"` |
+| `list_issues.py` | `[--status STATUS[,STATUS]] [--active] [--mine] [--limit N]` |
+| `get_issue.py` | `<ref> [--fields basic\|full]` |
+| `assign.py` | `<ref> <assignee>` |
+| `update_description.py` | `<ref> --text "..." \| --file PATH` |
+
+## Extended Scripts (cloud-only)
+
+| Script | Key Arguments |
+|--------|---------------|
+| `update_issue.py` | `<ref> [--priority 0-4] [--estimate 1-5] [--assignee STR] [--state STATUS] [--comment "..."]` |
+| `project_update.py` | `--health STATUS --body "..."` |
+| `estimate.py` / `priority.py` | `<ref> <value>` |
+| `link.py` | `<ref> <related_ref> <type>` |
+| `list_projects.py` / `create_project.py` | Project management |
+| `assign_cycle.py` / `list_cycles.py` | Cycle management |
+| `assign_milestone.py` / `list_milestones.py` / `create_milestone.py` | Milestone management |
+
+## Status Values
+
+`BACKLOG`, `READY`, `IMPLEMENTING`, `BLOCKED`, `REVIEW`, `TESTING`, `COMPLETE`, `ARCHIVED`, `CANCELED`, `DUPLICATE`
+
+## Error Handling
+
+Exit 0 = success (JSON on stdout). Exit 1 = error (message on stderr).
+Network errors: exponential backoff, 3 retries, 2s base delay.
+
+## Configuration
+
+Reads from `.flydocs/config.json`: tier, provider.teamId, statusMapping, issueLabels.
+Reads `LINEAR_API_KEY` from environment or `.env` / `.env.local`.

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

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""Assign an issue to a person."""
+
+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: assign.py <ref> <assignee>")
+
+ref, assignee_query = sys.argv[1], sys.argv[2]
+client = get_client()
+
+issue_uuid = client.resolve_issue_id(ref)
+if not issue_uuid:
+    fail(f"Issue not found: {ref}")
+
+user_id, user_name = client.resolve_user_id(assignee_query)
+if not user_id:
+    fail(f"User not found: {assignee_query}")
+
+result = client.query(
+    """mutation($id: String!, $assigneeId: String!) {
+        issueUpdate(id: $id, input: { assigneeId: $assigneeId }) {
+            success
+            issue { identifier }
+        }
+    }""",
+    {"id": issue_uuid, "assigneeId": user_id},
+)
+
+if not result.get("data", {}).get("issueUpdate", {}).get("success"):
+    fail(f"Failed to assign: {result}")
+
+issue = result["data"]["issueUpdate"]["issue"]
+output_json({"success": True, "issue": issue["identifier"], "assignee": user_name})

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

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""Assign an issue to a cycle (sprint)."""
+
+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) < 2:
+    fail("Usage: assign_cycle.py <ref> [cycle_id]")
+
+ref = sys.argv[1]
+client = get_client()
+
+issue_uuid = client.resolve_issue_id(ref)
+if not issue_uuid:
+    fail(f"Issue not found: {ref}")
+
+# Use specified cycle or active cycle
+cycle_id = sys.argv[2] if len(sys.argv) > 2 else None
+cycle_name = cycle_id or ""
+if not cycle_id:
+    cycle = client.get_active_cycle()
+    if not cycle:
+        fail("No active cycle found")
+    cycle_id = cycle["id"]
+    cycle_name = cycle["name"]
+
+result = client.query(
+    """mutation($id: String!, $cycleId: String!) {
+        issueUpdate(id: $id, input: { cycleId: $cycleId }) {
+            success
+            issue { identifier }
+        }
+    }""",
+    {"id": issue_uuid, "cycleId": cycle_id},
+)
+
+if not result.get("data", {}).get("issueUpdate", {}).get("success"):
+    fail(f"Failed to assign cycle: {result}")
+
+issue = result["data"]["issueUpdate"]["issue"]
+output_json({"success": True, "issue": issue["identifier"], "cycle": cycle_name})

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

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""Assign an issue to a milestone."""
+
+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="Assign issue to milestone")
+parser.add_argument("ref", help="Issue reference (e.g., ENG-123)")
+parser.add_argument("milestone_id", nargs="?", default=None,
+                    help="Milestone UUID (positional)")
+parser.add_argument("--milestone", dest="milestone_flag", default=None,
+                    help="Milestone UUID (flag)")
+args = parser.parse_args()
+
+milestone_id = args.milestone_flag or args.milestone_id
+if not milestone_id:
+    fail("Milestone ID required. Usage: assign_milestone.py <ref> <milestone_id> or --milestone <id>")
+
+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!, $milestoneId: String!) {
+        issueUpdate(id: $id, input: { projectMilestoneId: $milestoneId }) {
+            success
+            issue { identifier }
+        }
+    }""",
+    {"id": issue_uuid, "milestoneId": milestone_id},
+)
+
+update = result.get("data", {}).get("issueUpdate", {})
+if not update.get("success"):
+    fail(f"Failed to assign milestone: {result}")
+
+issue = update.get("issue", {})
+output_json({"success": True, "issue": issue.get("identifier", args.ref), "milestone": milestone_id})

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

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""Add a comment to 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) < 2:
+    fail("Usage: comment.py <ref> [<comment>]  (or pipe via stdin)")
+
+ref = sys.argv[1]
+body = sys.argv[2] if len(sys.argv) > 2 else ""
+if not body and not sys.stdin.isatty():
+    body = sys.stdin.read().strip()
+if not body:
+    fail("Provide comment as argument or pipe via stdin")
+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!, $body: String!) {
+        commentCreate(input: { issueId: $id, body: $body }) {
+            success
+            comment { id }
+        }
+    }""",
+    {"id": issue_uuid, "body": body},
+)
+
+data = result.get("data", {}).get("commentCreate", {})
+if not data.get("success"):
+    fail(f"Failed to add comment: {result}")
+
+output_json({"success": True, "commentId": data.get("comment", {}).get("id", "")})