@cliangdev/flux-plugin 0.2.0-dev.dc5e2c4 → 0.2.0-dev.f718bcf

package/src/server/tools/get-entity.ts

@@ -85,6 +85,10 @@ async function handler(input: unknown) {
     // Add available status transitions
     result.available_transitions = getValidTransitions(entityType, prd.status);
 
+    // Always include dependencies by default
+    const deps = await adapter.getDependencies(parsed.ref);
+    result.dependencies = deps;
+
     // Process includes
     for (const inc of includes) {
       if (!validIncludes.includes(inc)) continue;
@@ -166,6 +170,10 @@ async function handler(input: unknown) {
     result = { ...toMcpEpic(epic) };
     result.available_transitions = getValidTransitions(entityType, epic.status);
 
+    // Always include dependencies by default
+    const deps = await adapter.getDependencies(parsed.ref);
+    result.dependencies = deps;
+
     for (const inc of includes) {
       if (!validIncludes.includes(inc)) continue;
 
@@ -192,11 +200,6 @@ async function handler(input: unknown) {
         result.criteria_count = criteria.length;
         result.criteria_met = criteria.filter((c) => c.isMet).length;
       }
-
-      if (inc === "dependencies") {
-        const deps = await adapter.getDependencies(parsed.ref);
-        result.dependencies = deps;
-      }
     }
   } else {
     const task = await adapter.getTask(parsed.ref);
@@ -205,6 +208,10 @@ async function handler(input: unknown) {
     result = { ...toMcpTask(task) };
     result.available_transitions = getValidTransitions(entityType, task.status);
 
+    // Always include dependencies by default
+    const deps = await adapter.getDependencies(parsed.ref);
+    result.dependencies = deps;
+
     for (const inc of includes) {
       if (!validIncludes.includes(inc)) continue;
 
@@ -218,11 +225,6 @@ async function handler(input: unknown) {
         result.criteria_count = criteria.length;
         result.criteria_met = criteria.filter((c) => c.isMet).length;
       }
-
-      if (inc === "dependencies") {
-        const deps = await adapter.getDependencies(parsed.ref);
-        result.dependencies = deps;
-      }
     }
   }
 

package/src/server/tools/index.ts

@@ -7,11 +7,7 @@ import { z } from "zod";
 import { config } from "../config.js";
 import { logger } from "../utils/logger.js";
 
-const TOOLS_WITHOUT_PROJECT = [
-  "init_project",
-  "get_project_context",
-  "get_version",
-];
+const TOOLS_WITHOUT_PROJECT = ["init_project", "get_version"];
 
 export interface ToolDefinition {
   name: string;
@@ -26,10 +22,56 @@ export interface ToolError {
   code: string;
 }
 
+export interface ProjectNotInitializedError extends ToolError {
+  code: "PROJECT_NOT_INITIALIZED";
+  setup: {
+    instructions: string;
+    options: Array<{
+      method: "command" | "tool";
+      name: string;
+      description: string;
+      params?: Record<string, string>;
+    }>;
+  };
+}
+
 export function createError(message: string, code: string): ToolError {
   return { error: true, message, code };
 }
 
+export function createProjectNotInitializedError(
+  cwd: string,
+  projectRoot: string,
+): ProjectNotInitializedError {
+  return {
+    error: true,
+    code: "PROJECT_NOT_INITIALIZED",
+    message: `No Flux project found. Current directory: ${cwd}, resolved project root: ${projectRoot}`,
+    setup: {
+      instructions:
+        "Initialize a Flux project before using Flux tools. Use one of the following options:",
+      options: [
+        {
+          method: "command",
+          name: "/flux",
+          description:
+            "Interactive setup with guided prompts (recommended for first-time setup)",
+        },
+        {
+          method: "tool",
+          name: "init_project",
+          description: "Direct initialization via MCP tool",
+          params: {
+            name: "Project name (required)",
+            vision: "Brief project description (required)",
+            adapter: "local | linear (default: local)",
+          },
+        },
+      ],
+    },
+  };
+}
+
 export function registerTools(server: Server, tools: ToolDefinition[]) {
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: tools.map((t) => ({
@@ -60,13 +102,16 @@ export function registerTools(server: Server, tools: ToolDefinition[]) {
     }
 
     if (!TOOLS_WITHOUT_PROJECT.includes(toolName) && !config.projectExists) {
-      const message = `No Flux project found. Run init_project first or ensure you're in a directory with a .flux folder (or a subdirectory of one). Current directory: ${process.cwd()}, resolved project root: ${config.projectRoot}`;
-      logger.error(message);
+      const error = createProjectNotInitializedError(
+        process.cwd(),
+        config.projectRoot,
+      );
+      logger.error(error.message);
       return {
         content: [
           {
             type: "text",
-            text: JSON.stringify(createError(message, "PROJECT_NOT_FOUND")),
+            text: JSON.stringify(error, null, 2),
           },
         ],
         isError: true,
@@ -104,7 +149,6 @@ export { deleteEntityTool } from "./delete-entity.js";
 export { addDependencyTool, removeDependencyTool } from "./dependencies.js";
 export { getEntityTool } from "./get-entity.js";
 export { getLinearUrlTool } from "./get-linear-url.js";
-export { getProjectContextTool } from "./get-project-context.js";
 export { getStatsTool } from "./get-stats.js";
 export { getVersionTool } from "./get-version.js";
 export { initProjectTool } from "./init-project.js";

package/src/server/tools/init-project.ts

@@ -102,7 +102,7 @@ async function handler(input: unknown) {
 export const initProjectTool: ToolDefinition = {
   name: "init_project",
   description:
-    "Initialize a new Flux project. Required: name, vision. Optional: adapter (local|specflux|linear|notion, default 'local'). Creates .flux/ directory with project.json and SQLite database. Returns {success, project, message}. Fails if .flux/ already exists. Run get_project_context first to check.",
+    "Initialize a new Flux project. Required: name, vision. Optional: adapter (local|specflux|linear|notion, default 'local'). Creates .flux/ directory with project.json and SQLite database. Returns {success, project, message}. Fails if .flux/ already exists.",
   inputSchema,
   handler,
 };

package/src/server/tools/render-status.ts

@@ -23,6 +23,7 @@ interface EpicForSummary {
   status: string;
   task_count: number;
   tasks_completed: number;
+  dependencies: string[];
 }
 
 interface PrdForSummary {
@@ -30,12 +31,14 @@ interface PrdForSummary {
   title: string;
   status: string;
   epics: EpicForSummary[];
+  dependencies: string[];
 }
 
 interface TaskForFull {
   ref: string;
   title: string;
   status: string;
+  dependencies: string[];
 }
 
 interface EpicForFull {
@@ -43,6 +46,7 @@ interface EpicForFull {
   title: string;
   status: string;
   tasks: TaskForFull[];
+  dependencies: string[];
 }
 
 interface PrdForFull {
@@ -50,6 +54,7 @@ interface PrdForFull {
   title: string;
   status: string;
   epics: EpicForFull[];
+  dependencies: string[];
 }
 
 function getProjectInfo(): { name: string; ref_prefix: string } | null {
@@ -110,17 +115,17 @@ async function getSummaryData(adapter: Adapter): Promise<PrdForSummary[]> {
   const result: PrdForSummary[] = [];
 
   for (const prd of nonArchivedPrds) {
-    const epicsResult = await adapter.listEpics(
-      { prdRef: prd.ref },
-      { limit: 100 },
-    );
+    const [prdDeps, epicsResult] = await Promise.all([
+      adapter.getDependencies(prd.ref),
+      adapter.listEpics({ prdRef: prd.ref }, { limit: 100 }),
+    ]);
 
     const epicsWithCounts: EpicForSummary[] = await Promise.all(
       epicsResult.items.map(async (epic) => {
-        const tasksResult = await adapter.listTasks(
-          { epicRef: epic.ref },
-          { limit: 100 },
-        );
+        const [epicDeps, tasksResult] = await Promise.all([
+          adapter.getDependencies(epic.ref),
+          adapter.listTasks({ epicRef: epic.ref }, { limit: 100 }),
+        ]);
         const completedCount = tasksResult.items.filter(
           (t) => t.status === "COMPLETED",
         ).length;
@@ -131,6 +136,7 @@ async function getSummaryData(adapter: Adapter): Promise<PrdForSummary[]> {
           status: epic.status,
           task_count: tasksResult.total,
           tasks_completed: completedCount,
+          dependencies: epicDeps,
         };
       }),
     );
@@ -140,6 +146,7 @@ async function getSummaryData(adapter: Adapter): Promise<PrdForSummary[]> {
       title: prd.title,
       status: prd.status,
       epics: epicsWithCounts,
+      dependencies: prdDeps,
     });
   }
 
@@ -156,27 +163,37 @@ async function getFullTreeData(adapter: Adapter): Promise<PrdForFull[]> {
   const result: PrdForFull[] = [];
 
   for (const prd of allPrds) {
-    const epicsResult = await adapter.listEpics(
-      { prdRef: prd.ref },
-      { limit: 100 },
-    );
+    const [prdDeps, epicsResult] = await Promise.all([
+      adapter.getDependencies(prd.ref),
+      adapter.listEpics({ prdRef: prd.ref }, { limit: 100 }),
+    ]);
 
     const epicsWithTasks: EpicForFull[] = await Promise.all(
       epicsResult.items.map(async (epic) => {
-        const tasksResult = await adapter.listTasks(
-          { epicRef: epic.ref },
-          { limit: 100 },
+        const [epicDeps, tasksResult] = await Promise.all([
+          adapter.getDependencies(epic.ref),
+          adapter.listTasks({ epicRef: epic.ref }, { limit: 100 }),
+        ]);
+
+        // Get dependencies for each task
+        const tasksWithDeps: TaskForFull[] = await Promise.all(
+          tasksResult.items.map(async (t) => {
+            const taskDeps = await adapter.getDependencies(t.ref);
+            return {
+              ref: t.ref,
+              title: t.title,
+              status: t.status,
+              dependencies: taskDeps,
+            };
+          }),
         );
 
         return {
           ref: epic.ref,
           title: epic.title,
           status: epic.status,
-          tasks: tasksResult.items.map((t) => ({
-            ref: t.ref,
-            title: t.title,
-            status: t.status,
-          })),
+          tasks: tasksWithDeps,
+          dependencies: epicDeps,
         };
       }),
     );
@@ -186,6 +203,7 @@ async function getFullTreeData(adapter: Adapter): Promise<PrdForFull[]> {
       title: prd.title,
       status: prd.status,
       epics: epicsWithTasks,
+      dependencies: prdDeps,
     });
   }
 

package/src/status-line/__tests__/status-line.test.ts

@@ -31,7 +31,7 @@ function setupTestProject(testDir: string, projectName = "test-project") {
 }
 
 describe("status-line script", () => {
-  const TEST_DIR = `/tmp/flux-status-line-test-${Date.now()}`;
+  const TEST_DIR = `/tmp/flux-status-line-test-${Date.now()}-${Math.random().toString(36).slice(2)}`;
 
   beforeEach(() => {
     if (existsSync(TEST_DIR)) {

package/src/utils/status-renderer.ts

@@ -34,12 +34,14 @@ interface Epic {
   status: string;
   task_count: number;
   tasks_completed: number;
+  dependencies?: string[];
 }
 
 interface Task {
   ref: string;
   title: string;
   status: string;
+  dependencies?: string[];
 }
 
 interface EpicWithTasks {
@@ -47,6 +49,7 @@ interface EpicWithTasks {
   title: string;
   status: string;
   tasks: Task[];
+  dependencies?: string[];
 }
 
 interface Prd {
@@ -54,6 +57,7 @@ interface Prd {
   title: string;
   status: string;
   epics: Epic[];
+  dependencies?: string[];
 }
 
 interface PrdWithTasks {
@@ -61,6 +65,7 @@ interface PrdWithTasks {
   title: string;
   status: string;
   epics: EpicWithTasks[];
+  dependencies?: string[];
 }
 
 const STATUS_ORDER: Record<string, number> = {
@@ -117,13 +122,22 @@ export function renderSummaryView(
 
   for (const prd of sortedPrds) {
     const badge = getStatusBadge(prd.status);
-    lines.push(`${prd.ref} ${prd.title}  ${badge}`);
+    const prdBlocked = prd.dependencies && prd.dependencies.length > 0;
+    const prdBlockedBy = prdBlocked
+      ? ` ⚠️ blocked by: ${prd.dependencies?.join(", ")}`
+      : "";
+    lines.push(`${prd.ref} ${prd.title}  ${badge}${prdBlockedBy}`);
 
     for (const epic of prd.epics) {
       const icon = getStatusIcon(epic.status);
+      const epicBlocked = epic.dependencies && epic.dependencies.length > 0;
+      const epicBlockedBy = epicBlocked
+        ? ` ⚠️ blocked by: ${epic.dependencies?.join(", ")}`
+        : "";
+
       if (epic.task_count === 0) {
         lines.push(
-          `  ${icon} ${epic.ref} ${epic.title}  ·········· (no tasks)`,
+          `  ${icon} ${epic.ref} ${epic.title}  ·········· (no tasks)${epicBlockedBy}`,
         );
       } else {
         const epicProgress = renderProgressBar(
@@ -131,7 +145,7 @@ export function renderSummaryView(
           10,
         );
         lines.push(
-          `  ${icon} ${epic.ref} ${epic.title}  ${epicProgress} ${epic.tasks_completed}/${epic.task_count}`,
+          `  ${icon} ${epic.ref} ${epic.title}  ${epicProgress} ${epic.tasks_completed}/${epic.task_count}${epicBlockedBy}`,
         );
       }
     }
@@ -157,23 +171,35 @@ export function renderFullTreeView(prds: PrdWithTasks[]): string {
 
   for (const prd of sortedPrds) {
     const prdBadge = getStatusBadge(prd.status);
+    const prdBlocked = prd.dependencies && prd.dependencies.length > 0;
+    const prdBlockedBy = prdBlocked
+      ? `  ⚠️ blocked by: ${prd.dependencies?.join(", ")}`
+      : "";
     lines.push(`${prd.ref} ${prd.title}`);
-    lines.push(`${prdBadge}`);
+    lines.push(`${prdBadge}${prdBlockedBy}`);
     lines.push("");
 
     for (const epic of prd.epics) {
       const epicIcon = getStatusIcon(epic.status);
-      lines.push(`  ${epicIcon} ${epic.ref} ${epic.title}`);
+      const epicBlocked = epic.dependencies && epic.dependencies.length > 0;
+      const epicBlockedBy = epicBlocked
+        ? `  ⚠️ blocked by: ${epic.dependencies?.join(", ")}`
+        : "";
+      lines.push(`  ${epicIcon} ${epic.ref} ${epic.title}${epicBlockedBy}`);
 
       if (epic.tasks.length > 0) {
         lines.push(`  ┌${"─".repeat(50)}┐`);
 
         for (const task of epic.tasks) {
           const taskIcon = getStatusIcon(task.status);
+          const taskBlocked = task.dependencies && task.dependencies.length > 0;
+          const taskBlockedBy = taskBlocked
+            ? `  ⚠️ blocked by: ${task.dependencies?.join(", ")}`
+            : "";
           const currentMarker =
             task.status === "IN_PROGRESS" ? "  ← CURRENT" : "";
           lines.push(
-            `  │ ${taskIcon} ${task.ref} ${task.title}${currentMarker}`,
+            `  │ ${taskIcon} ${task.ref} ${task.title}${currentMarker}${taskBlockedBy}`,
           );
         }
 

package/skills/prd-template/SKILL.md

@@ -1,242 +0,0 @@
----
-name: flux:prd-template
-description: PRD structure and patterns for Flux. Use when creating or refining product requirement documents. PRDs should be concise for humans but detailed enough for AI agents to implement.
-user-invocable: false
----
-
-# PRD Template Skill
-
-PRDs should be **concise for human review** but contain **enough detail for AI implementation**.
-
-## PRD Structure (Required)
-
-```markdown
-# {Project Name}
-
-## Table of Contents
-- [Problem](#problem)
-- [Users](#users)
-- [Solution](#solution)
-- [Features (MVP)](#features-mvp)
-  - [P0: Must Have](#p0-must-have)
-  - [P1: Should Have](#p1-should-have)
-  - [Out of Scope](#out-of-scope)
-- [Constraints](#constraints)
-- [Open Questions](#open-questions)
-
-## Problem
-{2-3 sentences: What problem are we solving? Why does it matter?}
-
-## Users
-{Who has this problem? 1-2 user segments.}
-
-## Solution
-{1 paragraph: What are we building to solve this?}
-
-## Features (MVP)
-
-### P0: Must Have
-- **{Feature 1}**: {One sentence description}
-  - {Acceptance criterion 1}
-  - {Acceptance criterion 2}
-- **{Feature 2}**: {One sentence description}
-  - {Acceptance criterion}
-
-### P1: Should Have
-- **{Feature}**: {Description}
-
-### Out of Scope
-- {What we're NOT building}
-- {Future considerations}
-
-## Constraints
-- **Tech Stack**: {Required technologies, if any}
-- **Timeline**: {Any deadlines}
-- **Other**: {Budget, compliance, etc.}
-
-## Open Questions
-- {Unresolved decisions needing input}
-```
-
-### TOC Guidelines
-
-**For Local Adapter** (files in `.flux/prds/`):
-- Include TOC with anchor links (e.g., `[Problem](#problem)`)
-- Use lowercase with hyphens for anchors
-- Nest sub-sections under parent sections
-
-**For External Adapters** (Linear, Notion):
-- **Skip TOC** - External systems have their own navigation (Linear's outline, collapsible sections)
-- Linear generates unique anchor suffixes making pre-built links impossible
-
-## Guidelines
-
-### Keep It Short
-- Problem: 2-3 sentences max
-- Features: 3-5 P0 features for MVP
-- Each feature: 1 sentence + 2-4 acceptance criteria
-- Total PRD: 1-2 pages
-
-### Write for AI Implementation
-- Acceptance criteria should be testable
-- Use specific, unambiguous language
-- Include edge cases in criteria when important
-
-### Bad vs Good Examples
-
-**Bad feature:**
-> - User authentication
-
-**Good feature:**
-> - **User Authentication**: Users can sign up and log in with email/password
->   - Sign up requires email, password (min 8 chars), and name
->   - Login with email + password returns JWT token
->   - Invalid credentials show error message
->   - Forgot password sends reset email
-
-## Supporting Documents (Optional)
-
-Generate based on **agent confidence** and **user request**.
-
-| Document | When to Generate |
-|----------|------------------|
-| `architecture.md` | Complex systems, multiple components, API integrations |
-| `wireframes.md` | UI-heavy features, user specifically requests |
-| `data-model.md` | Custom data storage, complex relationships |
-| `user-flows.md` | Multi-step processes, complex user journeys |
-
-### Asking About Supporting Docs
-
-After PRD outline approval, ask:
-
-```
-PRD outline looks good. I can also generate:
-- Architecture diagram (recommended for this project)
-- UI wireframes
-- Data model
-
-Which would you like? Or should I proceed with just the PRD?
-```
-
-Recommend based on project type:
-- **Web App**: architecture, wireframes
-- **API/Backend**: architecture, data-model
-- **CLI Tool**: usually just PRD
-- **Mobile App**: architecture, wireframes
-
-## Supporting Doc Templates
-
-### architecture.md
-
-```markdown
-# Architecture
-
-## Overview
-{One paragraph system description}
-
-## Components
-
-```mermaid
-graph TB
-    Client[Client] --> API[API Server]
-    API --> DB[(Database)]
-    API --> Cache[(Redis)]
-```
-
-## API Endpoints
-
-| Method | Path | Description |
-|--------|------|-------------|
-| POST | /api/users | Create user |
-| GET | /api/users/:id | Get user |
-
-## Data Flow
-{Describe key data flows}
-
-## Tech Stack
-- **Frontend**: {tech}
-- **Backend**: {tech}
-- **Database**: {tech}
-```
-
-### wireframes.md
-
-```markdown
-# Wireframes
-
-## Screen: {Name}
-
-```
-+----------------------------------+
-|  Logo              [Login] [Sign Up]
-+----------------------------------+
-|                                  |
-|     Welcome to {App Name}        |
-|                                  |
-|     [  Email  ]                  |
-|     [Password ]                  |
-|     [  Login  ]                  |
-|                                  |
-|     Forgot password?             |
-+----------------------------------+
-```
-
-**Elements:**
-- Logo: links to home
-- Login button: submits form
-- Forgot password: opens reset flow
-```
-
-### data-model.md
-
-```markdown
-# Data Model
-
-## ERD
-
-```mermaid
-erDiagram
-    User ||--o{ Post : creates
-    Post ||--o{ Comment : has
-```
-
-## Tables
-
-### users
-| Column | Type | Constraints |
-|--------|------|-------------|
-| id | uuid | PK |
-| email | varchar | unique, not null |
-| created_at | timestamp | default now() |
-
-### posts
-| Column | Type | Constraints |
-|--------|------|-------------|
-| id | uuid | PK |
-| user_id | uuid | FK users.id |
-| content | text | not null |
-```
-
-## Workflow
-
-Check adapter type via `get_project_context` to determine storage behavior.
-
-### Local Adapter (`adapter.type === "local"`)
-
-1. **Interview** → Collect answers via AskUserQuestion
-2. **Outline** → Generate brief outline, ask for approval
-3. **Create entity** → Call `create_prd` with title and short description
-4. **Write PRD** → Write full PRD to `.flux/prds/{slug}/prd.md`
-5. **Set folder_path** → Call `update_entity` with `folder_path`: `.flux/prds/{slug}`
-6. **Ask about docs** → Offer relevant supporting docs
-7. **Generate docs** → Write requested docs to same folder
-
-### External Adapters (`adapter.type === "linear"`, `"notion"`, etc.)
-
-1. **Interview** → Collect answers via AskUserQuestion
-2. **Outline** → Generate brief outline, ask for approval
-3. **Create entity** → Call `create_prd` with title and short description
-4. **Sync content** → Call `update_entity` with `description`: Full PRD markdown content
-5. **Ask about docs** → Offer relevant supporting docs (stored as attachments in external system)
-
-**Note**: External adapters store all content in the external system. No local `.flux/prds/` files are created.

package/src/server/tools/get-project-context.ts

@@ -1,33 +0,0 @@
-import { existsSync, readFileSync } from "node:fs";
-import { z } from "zod";
-import { config } from "../config.js";
-import type { ToolDefinition } from "./index.js";
-
-const inputSchema = z.object({});
-
-async function handler(_input: unknown) {
-  const projectJsonPath = config.projectJsonPath;
-
-  if (!existsSync(projectJsonPath)) {
-    return { initialized: false };
-  }
-
-  try {
-    const content = readFileSync(projectJsonPath, "utf-8");
-    const project = JSON.parse(content);
-    return { initialized: true, ...project };
-  } catch (_err) {
-    return {
-      initialized: false,
-      error: "Failed to read project.json",
-    };
-  }
-}
-
-export const getProjectContextTool: ToolDefinition = {
-  name: "get_project_context",
-  description:
-    "Get project context from .flux/project.json. No parameters required. Returns {initialized: boolean, name?, vision?, ref_prefix?, adapter?: {type: 'local'|'specflux'|'linear'|'notion'}, created_at?}. Use this to check if a Flux project exists before other operations.",
-  inputSchema,
-  handler,
-};