@flydocs/cli 0.6.0-alpha.2 → 0.6.0-alpha.20

package/template/flydocs/knowledge/templates/note.md

@@ -0,0 +1,25 @@
+---
+title: "[Note title]"
+category: discovery | gotcha | optimization | debugging | integration
+created: YYYY-MM-DD
+lastUpdated: YYYY-MM-DD
+relatedIssues: []
+---
+
+# [Note Title]
+
+## Summary
+
+[One-paragraph summary of the discovery, gotcha, or learning.]
+
+## Details
+
+[Full explanation. Include code examples, error messages, or configuration details as relevant.]
+
+## Impact
+
+[What this affects — which parts of the system, which workflows, which developers need to know.]
+
+## Resolution / Workaround
+
+[If applicable — what was done to address this, or how to work around it.]

package/template/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.6.0-alpha.2",
+  "version": "0.6.0-alpha.20",
   "description": "FlyDocs Core - Manifest of all managed files",
   "repository": "github.com/plastrlab/flydocs-core",
 
@@ -9,17 +9,10 @@
     "owned_directories": {
       "description": "Entire directories owned by FlyDocs - contents replaced on update",
       "paths": [
-        ".flydocs/hooks",
         ".flydocs/templates",
+        ".claude/hooks",
         ".claude/agents",
         ".claude/skills/flydocs-workflow",
-        ".claude/skills/flydocs-cloud",
-        ".claude/skills/flydocs-local",
-        ".claude/skills/flydocs-figma",
-        ".claude/skills/flydocs-estimates",
-        ".claude/skills/flydocs-context-graph",
-        ".claude/skills/flydocs-context7",
-        ".flydocs/scripts",
         ".cursor/agents"
       ]
     },
@@ -45,6 +38,8 @@
         ".claude/commands/start-session.md",
         ".claude/commands/status.md",
         ".claude/commands/validate.md",
+        ".claude/commands/knowledge.md",
+        ".claude/commands/onboard.md",
         ".claude/commands/wrap-session.md",
         ".claude/skills/README.md",
         ".cursor/hooks.json",
@@ -80,6 +75,7 @@
             "statusMapping",
             "detectedStack",
             "skills",
+            "topology",
             "designSystem",
             "aiLabor"
           ]
@@ -96,6 +92,9 @@
         "flydocs/knowledge/product/personas.md",
         "flydocs/knowledge/product/user-flows.md",
         "flydocs/README.md",
+        "flydocs/knowledge/templates/decision.md",
+        "flydocs/knowledge/templates/feature.md",
+        "flydocs/knowledge/templates/note.md",
         "flydocs/design-system/README.md",
         "flydocs/design-system/token-mapping.md",
         "flydocs/design-system/component-patterns.md"
@@ -125,7 +124,9 @@
           "flydocs-update.md",
           "flydocs-upgrade.md",
           "implement.md",
+          "knowledge.md",
           "new-project.md",
+          "onboard.md",
           "project-update.md",
           "refine.md",
           "review.md",
@@ -134,6 +135,15 @@
           "validate.md",
           "wrap-session.md"
         ],
+        "hooks": [
+          "auto-approve.py",
+          "post-edit.py",
+          "post-pr-check.py",
+          "post-transition-check.py",
+          "prompt-submit.py",
+          "session-start.py",
+          "stop-gate.py"
+        ],
         "skills": {
           "root": ["README.md"],
           "flydocs-workflow": [
@@ -142,14 +152,9 @@
             "cursor-rule.mdc",
             "stages/",
             "templates/",
-            "reference/"
-          ],
-          "flydocs-cloud": ["SKILL.md", "cursor-rule.mdc", "scripts/"],
-          "flydocs-local": ["SKILL.md", "cursor-rule.mdc", "scripts/"],
-          "flydocs-figma": ["SKILL.md", "references/"],
-          "flydocs-estimates": ["SKILL.md", "references/"],
-          "flydocs-context-graph": ["SKILL.md", "schema.md", "scripts/"],
-          "flydocs-context7": ["SKILL.md", "cursor-rule.mdc", "scripts/"]
+            "reference/",
+            "scripts/"
+          ]
         }
       },
       ".cursor": {
@@ -163,8 +168,6 @@
       },
       ".flydocs": {
         "root": ["config.json", "version", "CHANGELOG.md"],
-        "scripts": ["generate_manifest.py", "skill_manager.py"],
-        "hooks": ["auto-approve.py", "post-edit.py", "prompt-submit.py"],
         "templates": ["bug.md", "chore.md", "feature.md", "idea.md"]
       },
       "flydocs": {
@@ -177,7 +180,8 @@
         ],
         "knowledge": {
           "root": ["INDEX.md", "README.md"],
-          "product": ["personas.md", "user-flows.md"]
+          "product": ["personas.md", "user-flows.md"],
+          "templates": ["decision.md", "feature.md", "note.md"]
         }
       },
       "root": ["AGENTS.md", ".env.example"]

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

@@ -1,111 +0,0 @@
----
-name: flydocs-cloud
-description: |
-  Connected issue management via FlyDocs Relay API.
-  Implements the FlyDocs mechanism contract with extended cloud operations.
-  All provider translation (Linear, Jira) happens server-side.
-triggers:
-  - create issue
-  - transition
-  - comment
-  - list issues
-  - assign
-  - update description
-  - update issue
-  - project update
-  - Linear
-  - cloud
----
-
-# FlyDocs Cloud Mechanism
-
-Issues managed via the FlyDocs Relay API. The relay handles provider translation server-side — scripts are thin REST wrappers.
-
-Reads config from `.flydocs/config.json` and API key (`FLYDOCS_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] [--labels "a,b"] [--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
-
-| Script                | Usage                                                                                                                                                                          | Output                                                 |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ |
-| `update_issue.py`     | `<ref> [--title "..."] [--priority 0-4] [--estimate 1-5] [--assignee STR] [--state STATUS] [--description "..."] [--description-file PATH] [--labels "a,b"] [--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}`                                           |
-| `assign_milestone.py` | `<ref> <milestone_id>`                                                                                                                                                         | `{success, issue, milestone}`                          |
-
-### Workspace Scripts
-
-| Script           | Usage                                                                 | Output                                                                    |
-| ---------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| `list_teams.py`  | (no args)                                                             | `[{id, name, key}]`                                                       |
-| `create_team.py` | `--name "..." [--key KEY] [--description "..."] [--parent <team_id>]` | `{id, name, key}` — `--parent` creates a sub-team                         |
-| `set_team.py`    | `<team_id>`                                                           | `{success}` — updates relay preference and local config `provider.teamId` |
-| `list_labels.py` | (no args)                                                             | `[{id, name, color}]` — requires team to be set first                     |
-| `set_labels.py`  | `--defaults '["a"]' --type-map '{"feature":["F"],...}' \| stdin`      | `{success, validated, defaults, typeMap}` — stores label config on relay  |
-
-### Script Notes
-
-- **How it works**: Scripts call the FlyDocs Relay REST API, which translates to the provider (Linear, Jira) server-side. Same interface and output as before — the transport changed from direct GraphQL to managed REST.
-- **`list_issues.py --active`**: Returns all non-terminal issues (excludes Done, Archived, Canceled, Duplicate).
-- **`list_issues.py --status`**: Accepts comma-separated statuses: `--status READY,IMPLEMENTING,BLOCKED`
-- **`get_issue.py --fields basic`**: Skips comment fetch for faster responses.
-- **`update_issue.py`**: Bulk update — sets multiple fields in a single API call. Prefer over separate scripts when updating more than one field.
-- **Shell-safe text input**: For text with special characters, pipe via stdin with a single-quoted heredoc:
-  ```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 server-side by the relay.
-
-## Error Handling
-
-Exit 0 = success (JSON on stdout). Exit 1 = error (message on stderr).
-Network errors: exponential backoff, 3 retries, 2s base delay.
-Relay errors include `code` and optional `provider_error` for debugging.
-
-## Configuration
-
-Reads from `.flydocs/config.json`: tier, relay URL override.
-Reads `FLYDOCS_API_KEY` from environment or `.env` / `.env.local`.
-
-Optional: `FLYDOCS_RELAY_URL` env var or `relay.url` in config to override the base URL (e.g., for local development).

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

@@ -1,50 +0,0 @@
----
-description: Connected issue management via FlyDocs Relay API — cloud mechanism for FlyDocs
-alwaysApply: true
----
-
-<!-- Condensed from SKILL.md — update both when changing patterns -->
-
-# FlyDocs Cloud Mechanism
-
-Issues managed via FlyDocs Relay API. Reads config from `.flydocs/config.json` and API key (`FLYDOCS_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
-
-| 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, relay URL override.
-Reads `FLYDOCS_API_KEY` from environment or `.env` / `.env.local`.

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

@@ -1,22 +0,0 @@
-#!/usr/bin/env python3
-"""Assign an issue to a user via the FlyDocs Relay API."""
-
-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 = sys.argv[1], sys.argv[2]
-client = get_client()
-
-result = client.post(f"/issues/{ref}/assign", {"assignee": assignee})
-
-output_json({
-    "success": result.get("success", True),
-    "issue": result.get("issue", ref),
-    "assignee": result.get("assignee", assignee),
-})

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

@@ -1,28 +0,0 @@
-#!/usr/bin/env python3
-"""Assign a cycle to an issue via the FlyDocs Relay API."""
-
-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]
-cycle_id = sys.argv[2] if len(sys.argv) >= 3 else None
-
-client = get_client()
-
-body: dict = {}
-if cycle_id:
-    body["cycleId"] = cycle_id
-
-result = client.put(f"/issues/{ref}/cycle", body)
-
-output_json({
-    "success": result.get("success", True),
-    "issue": result.get("issue", ref),
-    "cycle": result.get("cycle", ""),
-})

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

@@ -1,22 +0,0 @@
-#!/usr/bin/env python3
-"""Assign a milestone to an issue via the FlyDocs Relay API."""
-
-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_milestone.py <ref> <milestone_id>")
-
-ref, milestone_id = sys.argv[1], sys.argv[2]
-client = get_client()
-
-result = client.put(f"/issues/{ref}/milestone", {"milestoneId": milestone_id})
-
-output_json({
-    "success": result.get("success", True),
-    "issue": result.get("issue", ref),
-    "milestone": result.get("milestone", ""),
-})

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

@@ -1,29 +0,0 @@
-#!/usr/bin/env python3
-"""Add a comment to an issue via the FlyDocs Relay API."""
-
-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] | stdin")
-
-ref = sys.argv[1]
-
-# Comment from arg > stdin
-if len(sys.argv) >= 3:
-    body = sys.argv[2]
-elif not sys.stdin.isatty():
-    body = sys.stdin.read().strip()
-else:
-    fail("Provide comment as argument or via stdin")
-
-client = get_client()
-result = client.post(f"/issues/{ref}/comment", {"body": body})
-
-output_json({
-    "success": result.get("success", True),
-    "commentId": result.get("commentId", ""),
-})

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

@@ -1,63 +0,0 @@
-#!/usr/bin/env python3
-"""Create a new issue via the FlyDocs Relay API."""
-
-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="Create issue")
-    parser.add_argument("--title", required=True)
-    parser.add_argument("--type", required=True, choices=["feature", "bug", "chore", "idea"], dest="issue_type")
-    parser.add_argument("--description", default="")
-    parser.add_argument("--description-file", default="", dest="description_file")
-    parser.add_argument("--priority", type=int, default=3, choices=range(5))
-    parser.add_argument("--estimate", type=int, default=0, choices=[0, 1, 2, 3, 5])
-    parser.add_argument("--assignee", default=None)
-    parser.add_argument("--labels", default=None, help="Comma-separated ad-hoc label names")
-    parser.add_argument("--triage", action="store_true")
-    args = parser.parse_args()
-
-    # Resolve description: --description-file > stdin > --description
-    description = args.description
-    if args.description_file:
-        try:
-            description = Path(args.description_file).read_text()
-        except FileNotFoundError:
-            fail(f"File not found: {args.description_file}")
-    elif not description and not sys.stdin.isatty():
-        description = sys.stdin.read().strip()
-
-    body: dict = {
-        "title": args.title,
-        "type": args.issue_type,
-        "priority": args.priority,
-    }
-    if description:
-        body["description"] = description
-    if args.estimate:
-        body["estimate"] = args.estimate
-    if args.assignee:
-        body["assignee"] = args.assignee
-    if args.labels:
-        body["labels"] = [l.strip() for l in args.labels.split(",") if l.strip()]
-    if args.triage:
-        body["triage"] = True
-
-    client = get_client()
-    result = client.post("/issues", body)
-
-    output_json({
-        "id": result["id"],
-        "identifier": result["identifier"],
-        "title": result["title"],
-        "url": result["url"],
-    })
-
-
-if __name__ == "__main__":
-    main()

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

@@ -1,35 +0,0 @@
-#!/usr/bin/env python3
-"""Create a milestone via the FlyDocs Relay API."""
-
-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="Create milestone")
-    parser.add_argument("--name", required=True)
-    parser.add_argument("--project", default=None, help="Project ID")
-    parser.add_argument("--target-date", default=None, dest="target_date")
-    args = parser.parse_args()
-
-    body: dict = {"name": args.name}
-    if args.project:
-        body["projectId"] = args.project
-    if args.target_date:
-        body["targetDate"] = args.target_date
-
-    client = get_client()
-    result = client.post("/milestones", body)
-
-    output_json({
-        "id": result["id"],
-        "name": result["name"],
-    })
-
-
-if __name__ == "__main__":
-    main()

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

@@ -1,33 +0,0 @@
-#!/usr/bin/env python3
-"""Create a project via the FlyDocs Relay API."""
-
-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="Create project")
-    parser.add_argument("--name", required=True)
-    parser.add_argument("--description", default=None)
-    args = parser.parse_args()
-
-    body: dict = {"name": args.name}
-    if args.description:
-        body["description"] = args.description
-
-    client = get_client()
-    result = client.post("/projects", body)
-
-    output_json({
-        "id": result["id"],
-        "name": result["name"],
-        "url": result.get("url", ""),
-    })
-
-
-if __name__ == "__main__":
-    main()

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

@@ -1,39 +0,0 @@
-#!/usr/bin/env python3
-"""Create a team (or sub-team) via the FlyDocs Relay API."""
-
-import argparse
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).parent))
-from flydocs_api import get_client, output_json
-
-
-def main():
-    parser = argparse.ArgumentParser(description="Create team")
-    parser.add_argument("--name", required=True)
-    parser.add_argument("--key", default=None, help="Team key (e.g., PROD). Auto-generated if omitted.")
-    parser.add_argument("--description", default=None)
-    parser.add_argument("--parent", default=None, dest="parent_id", help="Parent team ID to create a sub-team")
-    args = parser.parse_args()
-
-    body: dict = {"name": args.name}
-    if args.key:
-        body["key"] = args.key
-    if args.description:
-        body["description"] = args.description
-    if args.parent_id:
-        body["parentId"] = args.parent_id
-
-    client = get_client()
-    result = client.post("/teams", body)
-
-    output_json({
-        "id": result["id"],
-        "name": result["name"],
-        "key": result.get("key", ""),
-    })
-
-
-if __name__ == "__main__":
-    main()

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

@@ -1,29 +0,0 @@
-#!/usr/bin/env python3
-"""Set estimate on an issue via the FlyDocs Relay API."""
-
-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: estimate.py <ref> <1-5>")
-
-ref = sys.argv[1]
-try:
-    estimate = int(sys.argv[2])
-except ValueError:
-    fail("Estimate must be a number (1-5)")
-
-if estimate not in (1, 2, 3, 5):
-    fail("Estimate must be 1 (XS), 2 (S), 3 (M), or 5 (L)")
-
-client = get_client()
-result = client.put(f"/issues/{ref}/estimate", {"estimate": estimate})
-
-output_json({
-    "success": result.get("success", True),
-    "issue": result.get("issue", ref),
-    "estimate": result.get("estimate", estimate),
-})