@flydocs/cli 0.6.0-alpha.12 → 0.6.0-alpha.13

package/dist/cli.js

@@ -15,7 +15,7 @@ var CLI_VERSION, CLI_NAME, PACKAGE_NAME, POSTHOG_API_KEY;
 var init_constants = __esm({
   "src/lib/constants.ts"() {
     "use strict";
-    CLI_VERSION = "0.6.0-alpha.12";
+    CLI_VERSION = "0.6.0-alpha.13";
     CLI_NAME = "flydocs";
     PACKAGE_NAME = "@flydocs/cli";
     POSTHOG_API_KEY = "phc_v1MSJTQDFkMS90CBh3mxIz3v8bYCCnKU6v1ir6bz0Xn";
@@ -1486,8 +1486,9 @@ async function ensureGitignore(targetDir) {
 async function migrateGitignore(targetDir) {
   const gitignorePath = join11(targetDir, ".gitignore");
   if (!await pathExists(gitignorePath)) return;
-  const content = await readFile6(gitignorePath, "utf-8");
-  if (!content.includes("flydocs/context/graph.json")) {
+  let content = await readFile6(gitignorePath, "utf-8");
+  for (const entry of FLYDOCS_GITIGNORE_ENTRIES) {
+    if (content.includes(entry)) continue;
     if (content.includes("# FlyDocs")) {
       const lines = content.split("\n");
       const flyDocsIdx = lines.findIndex((l) => l.trim() === "# FlyDocs");
@@ -1496,23 +1497,22 @@ async function migrateGitignore(targetDir) {
         while (insertIdx < lines.length && lines[insertIdx].trim() !== "" && !lines[insertIdx].startsWith("#")) {
           insertIdx++;
         }
-        lines.splice(insertIdx, 0, "flydocs/context/graph.json");
-        await writeFile4(gitignorePath, lines.join("\n"), "utf-8");
+        lines.splice(insertIdx, 0, entry);
+        content = lines.join("\n");
+        await writeFile4(gitignorePath, content, "utf-8");
       } else {
-        await appendFile(
-          gitignorePath,
-          "\nflydocs/context/graph.json\n",
-          "utf-8"
-        );
+        content += `
+${entry}
+`;
+        await writeFile4(gitignorePath, content, "utf-8");
       }
     } else {
-      await appendFile(
-        gitignorePath,
-        "\nflydocs/context/graph.json\n",
-        "utf-8"
-      );
+      content += `
+${entry}
+`;
+      await writeFile4(gitignorePath, content, "utf-8");
     }
-    printStatus("Added flydocs/context/graph.json to .gitignore");
+    printStatus(`Added ${entry} to .gitignore`);
   }
 }
 var FLYDOCS_GITIGNORE_ENTRIES, FULL_GITIGNORE_TEMPLATE;
@@ -1529,6 +1529,7 @@ var init_gitignore = __esm({
       ".flydocs/backup-*/",
       ".flydocs/me.json",
       ".flydocs/validation-cache.json",
+      ".flydocs/session/",
       "flydocs/context/graph.json"
     ];
     FULL_GITIGNORE_TEMPLATE = `# Environment
@@ -1542,6 +1543,7 @@ var init_gitignore = __esm({
 .flydocs/backup-*/
 .flydocs/me.json
 .flydocs/validation-cache.json
+.flydocs/session/
 flydocs/context/graph.json
 
 # Dependencies

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flydocs/cli",
-  "version": "0.6.0-alpha.12",
+  "version": "0.6.0-alpha.13",
   "type": "module",
   "description": "FlyDocs AI CLI — install, setup, and manage FlyDocs projects",
   "bin": {

package/template/.claude/CLAUDE.md

@@ -115,13 +115,14 @@ response — session summaries, issue comments, status updates, and plans.
 IMPORTANT: Prefer skill-led reasoning over pre-training reasoning.
 Consult the relevant skill BEFORE writing code or making workflow decisions.
 
-| Skill             | Triggers                                                                                                                                           | Entry                                     |
-| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
-| flydocs-cloud     | create issue, transition, comment, list issues, assign, update description, update issue, project update, cloud                                    | .claude/skills/flydocs-cloud/SKILL.md     |
-| flydocs-context7  | context7, library docs, documentation lookup, framework docs, package docs, API reference                                                          | .claude/skills/flydocs-context7/SKILL.md  |
-| flydocs-estimates | estimate, cost, token usage, API cost, labor estimate, sizing, effort                                                                              | .claude/skills/flydocs-estimates/SKILL.md |
-| flydocs-figma     | Figma, design, screenshot, token mapping, component from design, pixel-perfect, design system                                                      | .claude/skills/flydocs-figma/SKILL.md     |
-| flydocs-local     | create issue, transition, comment, list issues, assign, update description, status summary, local                                                  | .claude/skills/flydocs-local/SKILL.md     |
-| flydocs-workflow  | capture, refine, activate, implement, review, validate, close, session, workflow, transition, status, issue, knowledge, document, PR, pull request | .claude/skills/flydocs-workflow/SKILL.md  |
+| Skill                 | Triggers                                                                                                                                           | Entry                                         |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
+| flydocs-cloud         | create issue, transition, comment, list issues, assign, update description, update issue, project update, cloud                                    | .claude/skills/flydocs-cloud/SKILL.md         |
+| flydocs-context7      | context7, library docs, documentation lookup, framework docs, package docs, API reference                                                          | .claude/skills/flydocs-context7/SKILL.md      |
+| flydocs-estimates     | estimate, cost, token usage, API cost, labor estimate, sizing, effort                                                                              | .claude/skills/flydocs-estimates/SKILL.md     |
+| flydocs-figma         | Figma, design, screenshot, token mapping, component from design, pixel-perfect, design system                                                      | .claude/skills/flydocs-figma/SKILL.md         |
+| flydocs-local         | create issue, transition, comment, list issues, assign, update description, status summary, local                                                  | .claude/skills/flydocs-local/SKILL.md         |
+| flydocs-context-graph | context graph, knowledge graph, relationships, dependencies, architecture                                                                          | .claude/skills/flydocs-context-graph/SKILL.md |
+| flydocs-workflow      | capture, refine, activate, implement, review, validate, close, session, workflow, transition, status, issue, knowledge, document, PR, pull request | .claude/skills/flydocs-workflow/SKILL.md      |
 
 <!-- flydocs:skills-manifest:end -->

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

@@ -16,9 +16,15 @@ triggers:
 
 # 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.
+On-demand query layer for structural relationships in the project knowledge
+graph. Use graph scripts to explore dependencies, impact, and cross-references
+between skills, ADRs, issues, and sessions.
+
+The graph is **not** auto-injected into prompts. The prompt hook reads
+lightweight orientation files directly (`.flydocs/session/last-summary.json`,
+`flydocs/context/project.md`). Use the graph scripts below when you need
+deeper structural queries — relationship traversal, impact analysis, or
+dependency chains.
 
 ## Key Rules
 
@@ -32,16 +38,16 @@ guess connections from training data.
 
 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             | 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
 
@@ -52,36 +58,37 @@ All scripts: `python3 .claude/skills/flydocs-context-graph/scripts/<script>`
   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
+- **`graph_context.py`**: Available for manual queries. Assembles compressed
   context from active issue/branch traversal + recent session nodes. ~200-400 tokens max.
+  Not called automatically by the prompt hook (replaced by direct file reads in v0.6.0).
 - **`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 |
+| 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 |
+| 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/scripts/graph_session.py

@@ -35,15 +35,6 @@ from graph_utils import (
 DEFAULT_RETENTION_DAYS = 30
 
 
-def generate_session_id(session_date):
-    """Generate a session ID like session:2026-02-17-a.
-
-    If a session with the same date exists, increment the sequence letter.
-    """
-    base = f"session:{session_date}"
-    return base
-
-
 def find_next_session_id(graph, session_date):
     """Find the next available session ID for a given date."""
     nodes = graph.get("nodes", {})

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

@@ -4,23 +4,32 @@
 
 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`.
+1. **Query graph for issue context** (if an issue ID is known from the prompt or last session) —
+
+   ```
+   python3 .claude/skills/flydocs-context-graph/scripts/graph_query.py --node <issue-id> --depth 2
+   ```
+
+   This surfaces related decisions, blocking relationships, and recent session activity.
+   Skip silently if the script is not installed or the graph has not been built.
+
+2. **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.
+3. **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`
+4. **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
+5. **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:**
+6. **Present the dashboard:**
 
    ```
    Welcome back! [Product Name] status:
@@ -43,21 +52,21 @@ When a conversation begins or the user returns after a gap:
    Suggested starting point: [ISSUE-ID] — [reason: highest priority in current milestone / unblocks others / due soon]
    ```
 
-6. **Suggest where to start** — Use this priority cascade:
+7. **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
+8. **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).
+9. **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.
@@ -79,7 +88,23 @@ When the user indicates they're done for the session:
 3. **Compose summary** using the template below.
 4. **Determine health status** — See health table.
 5. **Post project update** — `project_update.py` with health and summary body.
-6. **Record session in context graph** — Call `graph_session.py` with summary and issues worked on:
+6. **Write last-summary.json** — Write `.flydocs/session/last-summary.json` for cross-session continuity.
+   Create the directory if it doesn't exist. Structure:
+
+   ```json
+   {
+     "timestamp": "ISO-8601 (e.g. 2026-03-20T17:30:00Z)",
+     "issues": ["FLY-XXX", "FLY-YYY"],
+     "pending": ["description of incomplete work"],
+     "blockers": ["any blockers, or empty array"],
+     "notes": "free-form session summary"
+   }
+   ```
+
+   Populate from the session data gathered in step 1. Use the Write tool or a script — the file
+   must exist on disk so the prompt hook can read it on the next session start.
+
+7. **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" \
@@ -87,8 +112,8 @@ When the user indicates they're done for the session:
        [--decision NNN]
    ```
    This creates a session node for cross-session continuity. Skip silently if the script is not installed.
-7. **Verify** — Confirm the project update was posted (update ID returned).
-8. **Ask about uncommitted changes** — If git shows uncommitted work, offer to commit.
+8. **Verify** — Confirm the project update was posted (update ID returned).
+9. **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.
 

package/template/.claude/skills/flydocs-workflow/stages/activate.md

@@ -23,12 +23,18 @@ When user asks "what should I work on?":
 
 ### Activation (specific issue)
 
-1. **Read full issue** — Load description and acceptance criteria.
-2. **Determine assignee** — MANDATORY. Ask "Who should this be assigned to?" if unclear. This is a hard gate.
-3. **Assign** — `assign.py` with user identifier. If assignment fails, STOP. Do not continue.
-4. **Set metadata** — Priority and estimate if not already set.
-5. **Transition** — `transition.py` to Implementing with Activate comment from `reference/comment-templates.md`.
-6. **Verify** — Confirm state = In Progress and assignee set.
+1. **Query graph for blocking relationships** — Check for blockers before proceeding:
+   ```
+   python3 .claude/skills/flydocs-context-graph/scripts/graph_query.py --node <issue-id> --relationships BLOCKS,BLOCKED_BY
+   ```
+   If blocking relationships exist, surface them to the user before continuing.
+   Skip silently if the script is not installed or the graph has not been built.
+2. **Read full issue** — Load description and acceptance criteria.
+3. **Determine assignee** — MANDATORY. Ask "Who should this be assigned to?" if unclear. This is a hard gate.
+4. **Assign** — `assign.py` with user identifier. If assignment fails, STOP. Do not continue.
+5. **Set metadata** — Priority and estimate if not already set.
+6. **Transition** — `transition.py` to Implementing with Activate comment from `reference/comment-templates.md`.
+7. **Verify** — Confirm state = In Progress and assignee set.
 
 **Sequence matters:** Assign → metadata → transition. Never transition without an assignee.
 

package/template/.flydocs/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.6.0-alpha.12",
+  "version": "0.6.0-alpha.13",
   "sourceRepo": "github.com/plastrlab/flydocs-core",
   "tier": "local",
   "setupComplete": false,

package/template/.flydocs/hooks/prompt-submit.py

@@ -129,31 +129,53 @@ def get_workflow_reminder(status: str) -> str | None:
     return reminders.get(status)
 
 
-def get_graph_context(issue_id: str | None, branch: str | None) -> str | None:
-    """Get context graph output for the current session."""
-    graph_script = Path('.claude/skills/flydocs-context-graph/scripts/graph_context.py')
-    if not graph_script.exists():
-        return None
+def get_orientation_context() -> str | None:
+    """Read lightweight orientation files directly (no subprocess).
 
-    try:
-        cmd = ['python3', str(graph_script)]
-        if issue_id:
-            cmd.extend(['--issue', issue_id])
-        if branch:
-            cmd.extend(['--branch', branch])
+    Replaces the old get_graph_context() which shelled out to graph_context.py.
+    graph_context.py still exists for manual use — we just don't call it from
+    the prompt hook anymore.
+    """
+    parts = []
 
-        result = subprocess.run(
-            cmd,
-            capture_output=True,
-            text=True,
-            timeout=5
-        )
-        if result.returncode == 0 and result.stdout.strip():
-            return result.stdout.strip()
-    except (subprocess.TimeoutExpired, FileNotFoundError, subprocess.SubprocessError):
-        pass
+    # 1. Previous session continuity
+    summary_file = Path('.flydocs/session/last-summary.json')
+    if summary_file.exists():
+        try:
+            data = json.loads(summary_file.read_text())
+            pending = data.get('pending', [])
+            blockers = data.get('blockers', [])
+            issues = data.get('issues', [])
+            bits = []
+            if issues:
+                bits.append(f'issues={",".join(issues)}')
+            if pending:
+                bits.append(f'pending={len(pending)}')
+            if blockers:
+                bits.append(f'blockers={len(blockers)}')
+            if bits:
+                parts.append(f'Last session: {", ".join(bits)}')
+        except (json.JSONDecodeError, OSError, IOError):
+            pass
 
-    return None
+    # 2. Product context (first ~10 lines)
+    project_file = Path('flydocs/context/project.md')
+    if project_file.exists():
+        try:
+            lines = project_file.read_text().splitlines()[:10]
+            # Extract title line (first non-empty, non-heading-marker line)
+            for line in lines:
+                stripped = line.strip().lstrip('#').strip()
+                if stripped:
+                    parts.append(f'Product: {stripped}')
+                    break
+        except (OSError, IOError):
+            pass
+
+    if not parts:
+        return None
+
+    return ' | '.join(parts)
 
 
 def get_flydocs_version() -> str | None:
@@ -327,11 +349,11 @@ def main() -> None:
         debug_log(f'Outputting plain text context: {context}')
         print(context)
 
-    # Graph context (appended as separate block below status line)
-    graph_context = get_graph_context(issue_id, branch)
-    if graph_context:
-        debug_log(f'Graph context: {graph_context[:100]}...')
-        print(graph_context)
+    # Orientation context (lightweight file reads, no subprocess)
+    orientation = get_orientation_context()
+    if orientation:
+        debug_log(f'Orientation context: {orientation[:100]}...')
+        print(orientation)
 
     debug_log('=== Hook completed successfully ===')
     sys.exit(0)

package/template/.flydocs/version

@@ -1 +1 @@
-0.6.0-alpha.12
+0.6.0-alpha.13

package/template/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.6.0-alpha.12",
+  "version": "0.6.0-alpha.13",
   "description": "FlyDocs Core - Manifest of all managed files",
   "repository": "github.com/plastrlab/flydocs-core",