@flydocs/cli 0.5.0-beta.0

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

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+"""Transition an issue to a new status."""
+
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import transition, STATUSES
+
+if len(sys.argv) < 4:
+    print("Usage: transition.py <ref> <STATUS> <comment>", file=sys.stderr)
+    sys.exit(1)
+
+try:
+    ref, status, comment = sys.argv[1], sys.argv[2].upper(), sys.argv[3]
+    if status not in STATUSES:
+        print(f"Invalid status: {status}. Valid: {', '.join(sorted(STATUSES.keys()))}", file=sys.stderr)
+        sys.exit(1)
+    result = transition(ref, status, comment)
+    print(json.dumps(result))
+except Exception as e:
+    print(str(e), file=sys.stderr)
+    sys.exit(1)

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

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""Update an issue's description."""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import update_description
+
+parser = argparse.ArgumentParser(description="Update issue description")
+parser.add_argument("ref")
+parser.add_argument("--text", default="")
+parser.add_argument("--file", default="", dest="filepath")
+
+try:
+    args = parser.parse_args()
+    text = args.text
+    if args.filepath:
+        try:
+            text = Path(args.filepath).read_text()
+        except FileNotFoundError:
+            print(f"File not found: {args.filepath}", file=sys.stderr)
+            sys.exit(1)
+    if not text and not sys.stdin.isatty():
+        text = sys.stdin.read().strip()
+    if not text:
+        print("Provide --text, --file, or pipe via stdin", file=sys.stderr)
+        sys.exit(1)
+    result = update_description(args.ref, text)
+    print(json.dumps(result))
+except Exception as e:
+    print(str(e), file=sys.stderr)
+    sys.exit(1)

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

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Bulk update an issue — set multiple fields in a single operation."""
+
+import argparse
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import _find_issue, _parse_issue, _write_issue, add_comment
+from flydocs_api import transition as do_transition
+
+parser = argparse.ArgumentParser(description="Update issue fields")
+parser.add_argument("ref", help="Issue reference (e.g., FD-001)")
+parser.add_argument("--title", default=None)
+parser.add_argument("--priority", type=int, choices=range(5), default=None)
+parser.add_argument("--estimate", type=int, choices=range(1, 6), default=None)
+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)
+
+try:
+    args = parser.parse_args()
+
+    updated_fields = []
+
+    # Handle state transition first (moves the file between directories)
+    if args.state:
+        do_transition(args.ref, args.state.upper(), f"Status changed to {args.state.upper()}")
+        updated_fields.append("state")
+
+    # Handle comment next (appends to file via add_comment)
+    if args.comment:
+        add_comment(args.ref, args.comment)
+        updated_fields.append("comment")
+
+    # Now read the current state of the file (after any transition/comment writes)
+    filepath = _find_issue(args.ref)
+    data = _parse_issue(filepath)
+
+    if args.title is not None:
+        data["title"] = args.title
+        updated_fields.append("title")
+
+    if args.priority is not None:
+        data["priority"] = args.priority
+        updated_fields.append("priority")
+
+    if args.estimate is not None:
+        data["estimate"] = args.estimate
+        updated_fields.append("estimate")
+
+    if args.assignee is not None:
+        data["assignee"] = args.assignee
+        updated_fields.append("assignee")
+
+    description = data.get("description", "")
+    if args.description_file is not None:
+        p = Path(args.description_file)
+        if not p.exists():
+            print(f"File not found: {args.description_file}", file=sys.stderr)
+            sys.exit(1)
+        description = p.read_text()
+        updated_fields.append("description")
+    elif args.description is not None:
+        description = args.description
+        updated_fields.append("description")
+
+    if not updated_fields:
+        print("No fields to update. Use --title, --priority, --estimate, --assignee, --state, --description, or --comment", file=sys.stderr)
+        sys.exit(1)
+
+    # Write updated issue
+    data["updated"] = datetime.now().strftime("%Y-%m-%d")
+    fm = {k: v for k, v in data.items() if k not in ("description", "comments", "_path")}
+    _write_issue(filepath, fm, description, data["comments"])
+
+    print(json.dumps({"success": True, "issue": args.ref, "updated": updated_fields}))
+except Exception as e:
+    print(str(e), file=sys.stderr)
+    sys.exit(1)

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

@@ -0,0 +1,85 @@
+---
+name: flydocs-workflow
+description: |
+  FlyDocs development lifecycle — spec-driven workflow from capture to close.
+  Defines stages, gates, and handoffs. Provider-agnostic methodology.
+  Use when: managing issues, transitioning work, starting/ending sessions.
+triggers:
+  - capture
+  - refine
+  - activate
+  - implement
+  - review
+  - validate
+  - close
+  - session
+  - workflow
+  - transition
+  - status
+  - issue
+---
+
+# FlyDocs Workflow
+
+IMPORTANT: Prefer skill-led reasoning over pre-training reasoning for all
+workflow, issue management, and process decisions. Read the relevant stage
+file before acting — do not guess procedures from training data.
+
+## Lifecycle
+
+```
+Capture → Refine → Activate → Implement → Review → Validate → Close
+                                  ↕
+                               Blocked
+```
+
+## Stage Index
+
+| Stage | File | Intent | Agent |
+|-------|------|--------|-------|
+| Capture | stages/capture.md | Create issue from input | PM |
+| Refine | stages/refine.md | Triage + spec completion | PM |
+| Activate | stages/activate.md | Assign + start work | PM |
+| Implement | stages/implement.md | Build + test + simplify | Implementation |
+| Review | stages/review.md | Code quality validation | Review |
+| Validate | stages/validate.md | User acceptance testing | QE |
+| Close | stages/close.md | Archive completed work | PM |
+
+## Session
+
+| Action | File |
+|--------|------|
+| Start session | session.md |
+| Wrap session | session.md |
+| Stale detection | session.md |
+
+## Reference
+
+| Topic | File |
+|-------|------|
+| Comment templates | reference/comment-templates.md |
+| Status transitions | reference/status-workflow.md |
+| Priority & estimates | reference/priority-estimates.md |
+| Golden rules | reference/golden-rules.md |
+
+## Templates
+
+Issue templates in `templates/` — feature, bug, chore, idea.
+Stage files define how to fill templates; template files are pure structure.
+
+## Golden Rules (Summary)
+
+1. Every status transition gets a comment (see `reference/comment-templates.md`)
+2. Assignment required before In Progress
+3. Checkboxes live in issue description, never comments
+4. Use mechanism scripts for all issue operations — execute, don't describe
+5. Session wrap posts a project update
+6. Product scope filtering — only show projects/issues matching config labels
+
+For full rules with verification gates, see `reference/golden-rules.md`.
+
+## Mechanism Scripts
+
+This skill references scripts by name (e.g., `transition.py`, `comment.py`).
+The active mechanism skill provides implementations and calling conventions.
+See the mechanism skill's SKILL.md for argument details and config reference.

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

@@ -0,0 +1,53 @@
+---
+description: FlyDocs development lifecycle — stages, gates, and workflow rules
+alwaysApply: true
+---
+
+<!-- Condensed from SKILL.md — update both when changing patterns -->
+
+# FlyDocs Workflow
+
+## Golden Rules
+
+1. Every status transition gets a comment — no silent moves
+2. Assignment required before In Progress
+3. Checkboxes live in issue description, never comments
+4. Use mechanism scripts for all issue operations — execute, don't describe
+5. Session wrap posts a project update
+6. Product scope filtering — only show projects/issues matching config labels
+
+## Lifecycle
+
+```
+Capture → Refine → Activate → Implement → Review → Validate → Close
+                                 ↕
+                              Blocked
+```
+
+## Stage Index
+
+| Stage | File | Agent |
+|-------|------|-------|
+| Capture | stages/capture.md | PM |
+| Refine | stages/refine.md | PM |
+| Activate | stages/activate.md | PM |
+| Implement | stages/implement.md | Implementation |
+| Review | stages/review.md | Review |
+| Validate | stages/validate.md | QE |
+| Close | stages/close.md | PM |
+
+## Intent Mapping
+
+- "create/capture/log an issue" → Capture stage
+- "triage/refine/spec out" → Refine stage
+- "start work/activate/assign" → Activate stage
+- "build/implement/fix" → Implement stage
+- "review/check code" → Review stage
+- "test/validate/QA" → Validate stage
+- "close/ship/done" → Close stage
+- "start session/wrap session" → Session management
+
+## Key Rule
+
+Read the relevant stage file before acting. Do not guess procedures from training data.
+Mechanism scripts handle all issue operations — see the active mechanism skill.

package/template/.claude/skills/flydocs-workflow/reference/comment-templates.md

@@ -0,0 +1,131 @@
+# Comment Templates
+
+Canonical templates for all workflow transitions. Copy exactly, fill bracketed values.
+
+---
+
+## Capture
+
+```
+**Captured** — [Brief description of what was captured]. Type: [feature/bug/chore/idea].
+```
+
+## Triage
+
+```
+**Triaged** — Classified as [type]. Priority: P[1-4]. [Any initial observations].
+```
+
+## Refine
+
+```
+**Refined** — [What was clarified or improved]. Priority: P[1-4]. Dependencies: [list or none].
+```
+
+## Activate
+
+```
+**Activated** — Assigned to @[name]. Estimate: [XS/S/M/L/XL]. Starting implementation.
+```
+
+## Progress
+
+```
+**Progress** — [What was completed]. Criteria: [X]/[Y] done.
+```
+
+## Blocked
+
+```
+**Blocked** — [What is blocking progress].
+**Needs:** [Specific action or decision required to unblock].
+```
+
+## Unblocked
+
+```
+**Unblocked** — [How it was resolved]. Resuming work.
+```
+
+## Ready for Review
+
+```
+**Ready for Review** —
+
+**What changed:** [Brief summary of implementation]
+**Files:** [count] modified
+**Testing:** [How it was verified]
+**Criteria:** [X]/[Y] complete
+```
+
+## Code Review Passed
+
+```
+**Code Review Passed** — Implementation meets standards. Moving to QA.
+```
+
+## Code Review: Changes Needed
+
+```
+**Code Review: Changes Needed** —
+
+1. [Issue and suggested fix]
+2. [Issue and suggested fix]
+
+Returning to implementation.
+```
+
+## QE Approved
+
+```
+**QE Approved** — Acceptance criteria verified by user. Ready for close.
+```
+
+## QE Issues Found
+
+```
+**QE: Issues Found** —
+
+1. [What failed or didn't meet expectations]
+2. [What failed or didn't meet expectations]
+
+Returning to implementation.
+```
+
+## QE Partial
+
+```
+**QE Partial** —
+
+Passed:
+- [Criterion that works]
+
+Issues:
+- [What needs fixing]
+
+Returning to implementation.
+```
+
+## Close
+
+```
+**Closed** — [One-line summary of what was delivered].
+```
+
+## Archive
+
+```
+**Archived** — Deferring. Reason: [why not now].
+```
+
+## Cancel
+
+```
+**Canceled** — Not pursuing. Reason: [why].
+```
+
+## Duplicate
+
+```
+**Duplicate** — See [ISSUE-ID].
+```

package/template/.claude/skills/flydocs-workflow/reference/golden-rules.md

@@ -0,0 +1,76 @@
+# Golden Rules
+
+Non-negotiable rules enforced across all workflow stages.
+
+---
+
+## The Rules
+
+### 1. Every Status Transition Gets a Comment
+
+No silent state changes. Use templates from `reference/comment-templates.md`.
+Mechanism scripts enforce this — `transition.py` requires a comment argument.
+
+### 2. Assignment Before In Progress
+
+An issue cannot move to Implementing without an assignee. This is a hard gate.
+The Activate stage enforces: assign → metadata → transition. Never skip assignment.
+
+### 3. Checkboxes in Description, Never Comments
+
+Acceptance criteria progress is tracked by checking boxes in the issue description.
+Never put completion marks in comments. Never create new checkboxes in comments.
+See the Checkbox Protocol in `stages/implement.md`.
+
+### 4. Use Mechanism Scripts — Execute, Don't Describe
+
+For all issue operations (create, transition, comment, assign, query), use the scripts
+provided by the active mechanism skill. Run them. Do not say "you should run..." or
+describe what a script would do. Execute and report the result.
+
+### 5. Session Wrap Posts a Project Update
+
+Every session wrap posts a project update via `project_update.py`. Do not just
+summarize in chat. Actually post. See `session.md` for the full protocol.
+
+### 6. Product Scope Filtering
+
+`list_issues.py` automatically applies product scope from config using this cascade:
+
+1. **`workspace.activeProjects` set** → scope to those projects (OR logic if multiple)
+2. **`workspace.product.labelIds` set** → scope to issues with ALL those labels (AND logic)
+3. **Neither set** → team-wide (no additional filter)
+
+Explicit `--project` flag always overrides the cascade. The `--active` and `--status` flags
+work within the scoped results — they do not bypass product scope.
+
+Never show out-of-scope issues, even if the user asks.
+
+---
+
+## Verification Gates
+
+After executing any workflow command, verify the result before responding:
+
+| Action | Script Used | Verify |
+|--------|-------------|--------|
+| Capture | `create_issue.py` | Issue identifier returned |
+| Refine | `transition.py` → READY | Success response |
+| Activate | `assign.py` + `transition.py` | Both succeed |
+| Implement | `get_issue.py` | Issue details loaded |
+| Block | `transition.py` → BLOCKED | Success response |
+| Review | `transition.py` → REVIEW/TESTING | Success response |
+| Validate | `transition.py` → TESTING/IMPLEMENTING | Success response |
+| Close | `transition.py` → COMPLETE | Success response |
+| Wrap | `project_update.py` | Update ID returned |
+
+If any script fails: **stop, report, retry, escalate.** Do not continue to the next step.
+
+---
+
+## Error Recovery
+
+1. **Stop** — Don't continue to the next step
+2. **Report** — Tell the user what failed
+3. **Retry** — Attempt the failed step again
+4. **Escalate** — If still failing, ask the user for help

package/template/.claude/skills/flydocs-workflow/reference/priority-estimates.md

@@ -0,0 +1,28 @@
+# Priority & Estimates
+
+## Priority Values
+
+| Value | Name | Use When |
+|-------|------|----------|
+| 0 | None | Not yet triaged |
+| 1 | Urgent | Drop everything, fix now |
+| 2 | High | Next up, unblocks others |
+| 3 | Medium | Normal priority (default) |
+| 4 | Low | Nice to have |
+
+## Estimate Values (Complexity)
+
+| Value | Name | Rough Effort |
+|-------|------|--------------|
+| 1 | XS | < 1 hour |
+| 2 | S | 1-4 hours |
+| 3 | M | Half day to full day |
+| 4 | L | 2-3 days |
+| 5 | XL | Week+ |
+
+## Guidance
+
+- Set priority during Refine or Activate stages
+- Set estimate during Refine stage (before Ready)
+- If estimate is missing at Activate, set it before transitioning
+- XL estimates often indicate the issue should be broken into smaller pieces

package/template/.claude/skills/flydocs-workflow/reference/status-workflow.md

@@ -0,0 +1,50 @@
+# Status Workflow
+
+## Lifecycle Diagram
+
+```
+BACKLOG ──→ READY ──→ IMPLEMENTING ──→ REVIEW ──→ TESTING ──→ COMPLETE
+                           ↕               ↕          ↕
+                        BLOCKED ◄──────────┘──────────┘
+```
+
+## State Meanings
+
+| FlyDocs State | Intent | Assignment Required |
+|---------------|--------|---------------------|
+| BACKLOG | Raw capture, not yet refined | No |
+| READY | Refined spec, ready to pick up | No |
+| IMPLEMENTING | Active work in progress | **Yes** |
+| BLOCKED | Cannot proceed, waiting on resolution | Yes |
+| REVIEW | Code complete, awaiting quality review | Yes |
+| TESTING | Review passed, awaiting user acceptance | Yes |
+| COMPLETE | All stages passed, work delivered | Yes |
+
+## Valid Transitions
+
+| From | To | Trigger |
+|------|----|---------|
+| BACKLOG | READY | Refine stage completes |
+| READY | IMPLEMENTING | Activate stage completes |
+| IMPLEMENTING | REVIEW | Implement stage completes |
+| IMPLEMENTING | BLOCKED | Blocker identified |
+| BLOCKED | IMPLEMENTING | Blocker resolved |
+| REVIEW | TESTING | Code review passes |
+| REVIEW | IMPLEMENTING | Code review finds issues |
+| TESTING | COMPLETE | QE approves, PM closes |
+| TESTING | IMPLEMENTING | QE finds issues |
+
+## Terminal States
+
+| State | When |
+|-------|------|
+| COMPLETE (Done) | Work delivered and verified |
+| ARCHIVED | Deferred — may return later |
+| CANCELED | Not pursuing |
+| DUPLICATE | See referenced issue |
+
+## Provider Mapping
+
+FlyDocs states are provider-agnostic. The mechanism skill maps them to provider-specific
+state names via `statusMapping` in `.flydocs/config.json`. The workflow never references
+provider-specific names directly.

package/template/.claude/skills/flydocs-workflow/session.md

@@ -0,0 +1,128 @@
+# Session Management
+
+## Session Start
+
+When a conversation begins or the user returns after a gap:
+
+1. **Fetch all product issues in one call** — Run `list_issues.py --active --limit 100`.
+   This is auto-scoped by the product cascade: `activeProjects` → `product.labelIds` → team-wide.
+   Issues outside the product scope are never shown.
+
+2. **Identify the active project** — Read `workspace.activeProjects` from config.
+   Separate issues into two buckets:
+   - **Active project issues** — issues whose `projectId` matches an active project
+   - **Other product issues** — issues in the product scope but in a different project
+
+3. **Group active project issues by milestone** — Use the `milestone` and `milestoneSortOrder`
+   fields returned by the script. Sort milestones by `milestoneSortOrder` (lowest first = earliest).
+   Within each milestone, group by status.
+
+4. **Identify the current milestone** — The first milestone (by sort order) that still has
+   open issues. This is where work should focus.
+
+5. **Present the dashboard:**
+
+   ```
+   Welcome back! [Product Name] status:
+
+   Active project: [Project Name]
+   Current milestone: [Milestone Name] — [X of Y issues open]
+
+   ## [Current Milestone Name]
+   - [N] in progress — [list identifiers]
+   - [N] blocked — [list identifiers, flag for attention]
+   - [N] in review — [list identifiers]
+   - [N] ready — [list identifiers, ordered by priority]
+
+   ## [Next Milestone Name] (upcoming)
+   - [N] total issues (brief summary only)
+
+   ## Unassigned to milestone
+   - [issues not in any milestone, if any]
+
+   Suggested starting point: [ISSUE-ID] — [reason: highest priority in current milestone / unblocks others / due soon]
+   ```
+
+6. **Suggest where to start** — Use this priority cascade:
+   - Blocked issues that need unblocking (always surface first)
+   - In-progress issues (continue existing work)
+   - Due date approaching (within 7 days)
+   - Highest priority in the current milestone
+   - Issues that unblock downstream milestones
+
+7. **Surface other product issues briefly** — If there are issues in the product scope
+   but outside the active project, mention the count with a one-line summary:
+   ```
+   Also in [Product Name]: [N] issues across other projects (use --all to see)
+   ```
+
+8. **Check for stale issues** — Flag issues exceeding staleness thresholds (see below).
+
+**Important:** Do NOT make separate API calls per status or per milestone. One call returns
+all issues with their status and milestone fields — group them in your response.
+
+**Important:** Never show issues outside the product scope. The script handles this
+automatically via the config cascade.
+
+## Session Wrap
+
+When the user indicates they're done for the session:
+
+1. **Gather session data** — What was completed, what's in progress, what's blocked.
+2. **Compose summary** using the template below.
+3. **Determine health status** — See health table.
+4. **Post project update** — `project_update.py` with health and summary body.
+5. **Record session in context graph** — Call `graph_session.py` with summary and issues worked on:
+   ```
+   python3 .claude/skills/flydocs-context-graph/scripts/graph_session.py \
+       --summary "Brief summary of session outcomes" \
+       --issue ISSUE-ID [--issue ISSUE-ID2] \
+       [--decision NNN]
+   ```
+   This creates a session node for cross-session continuity. Skip silently if the script is not installed.
+6. **Verify** — Confirm the project update was posted (update ID returned).
+7. **Ask about uncommitted changes** — If git shows uncommitted work, offer to commit.
+
+Do not just summarize in chat. Actually post the update. Do not skip if the user seems in a hurry.
+
+### Summary Template
+
+```
+**Session Summary — [YYYY-MM-DD]**
+
+**Completed:**
+- [ISSUE-ID] — [What was done]
+
+**In Progress:**
+- [ISSUE-ID] — [Current state, what's next]
+
+**Next Up:**
+- [ISSUE-ID] — [Why this is next]
+
+**Blockers:** [None / List with details]
+```
+
+### Health Status
+
+| Status | When to Use |
+|--------|-------------|
+| onTrack | Progress made, no blockers |
+| atRisk | Minor delays, attention needed |
+| offTrack | Major blockers, behind schedule |
+
+### Wrap Detection Phrases
+
+Offer session wrap when the user says:
+- "I'm done for today" / "wrapping up" / "that's it for now"
+- "save progress" / "end of day" / "stopping here"
+
+## Stale Issue Awareness
+
+Proactively surface issues that may be stuck:
+
+| State | Threshold | Action |
+|-------|-----------|--------|
+| Implementing | > 7 days without activity | Warn |
+| Review | > 3 days without activity | Warn |
+| Testing/QA | > 3 days without activity | Warn |
+| Blocked | Any | Always surface |