@cliangdev/flux-plugin 0.1.0-dev.588ae42 → 0.2.0-dev.4f12f3f

package/commands/breakdown.md

@@ -16,10 +16,10 @@ Check if arguments were provided:
 
 ## Pre-checks
 
-1. Call `get_project_context` to ensure Flux is initialized
-   - If not initialized, tell user: "Run `/flux` first to initialize the project."
+1. If no ref provided, call `query_entities` with type=prd, status=APPROVED
+   - If error with `code: "PROJECT_NOT_INITIALIZED"`, tell user: "Run `/flux` first to initialize the project." and exit.
 
-2. If no ref provided, call `query_entities` with type=prd, status=APPROVED
+2. If query successful but no approved PRDs found:
    - If no approved PRDs, tell user: "No approved PRDs found. Approve a PRD first or run `/flux:prd` to create one."
    - If multiple approved PRDs, use AskUserQuestion to let user select which one
 

package/commands/flux.md

@@ -6,27 +6,78 @@ allowed-tools: mcp__plugin_flux_flux__*, AskUserQuestion, Read, Write
 
 # Flux Command
 
-You are the Flux orchestrator. Detect project state and guide the user to the appropriate next action.
+You are the Flux orchestrator - the main entry point for all Flux operations. Your job is to:
+1. Detect project state and guide users to the appropriate next action
+2. Route to specialized commands based on user input
+3. Provide intelligent suggestions based on workflow state
+
+## Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `/flux` | Show project status and suggest next action |
+| `/flux:prd` | Create or refine PRDs through guided interview |
+| `/flux:breakdown` | Break approved PRD into dependency-ordered epics and tasks |
+| `/flux:implement` | Implement tasks with TDD workflow using specialized coding agents |
+| `/flux:linear` | Connect Flux project to Linear for issue tracking |
+
+## Subcommand Routing
+
+When user provides arguments, route to the appropriate command:
+
+| User Input | Action |
+|------------|--------|
+| `/flux` | Show status (see Main Flow) |
+| `/flux version` | Call `get_version` and display result |
+| `/flux status` | Call `render_status` with `{view: "full"}` |
+| `/flux prd` or `/flux prd ...` | Delegate to `/flux:prd` with any additional args |
+| `/flux breakdown` or `/flux breakdown ...` | Delegate to `/flux:breakdown` with any additional args |
+| `/flux implement` or `/flux implement ...` | Delegate to `/flux:implement` with any additional args |
+| `/flux linear` | Delegate to `/flux:linear` |
+| `/flux help` | Show available commands and their purposes |
+
+## Available MCP Tools
+
+These tools are available for programmatic access:
+
+**Entity Management:**
+- `create_prd`, `create_epic`, `create_task` - Create entities
+- `update_entity`, `update_status`, `delete_entity` - Modify entities
+- `get_entity`, `query_entities` - Retrieve entities
+
+**Project:**
+- `init_project` - Initialize new Flux project
+- `get_stats` - Get entity counts by status
+- `get_version` - Get plugin version
+- `render_status` - Visual project status with progress bars
+
+**Relationships:**
+- `add_dependency`, `remove_dependency` - Task/epic dependencies
+- `add_criteria`, `mark_criteria_met` - Acceptance criteria
+
+**Integration:**
+- `configure_linear` - Connect to Linear (interactive mode supported)
 
-## Subcommands
+## Main Flow
 
-- `/flux version` - Show plugin version (call `get_version`)
-- `/flux linear` - Connect to Linear (delegate to `/flux:linear`)
+### Step 0: Check for Subcommands
 
-## Main Flow
+First, check if the user provided arguments (e.g., `/flux prd`, `/flux implement FP-T1`).
+If so, route to the appropriate command as described in Subcommand Routing above.
 
-### Step 1: Get Project Context
+### Step 1: Check Project State
 
-Call `get_project_context` to check project state.
+If no subcommand, call `render_status` with `{view: "summary"}` to show current state.
 
-### Step 2: Route Based on State
+### Step 2: Route Based on Response
 
-**If `initialized: false`:**
+**If error with `code: "PROJECT_NOT_INITIALIZED"`:**
 → Guide through initialization (see Initialization Flow below)
 
-**If `initialized: true`:**
-→ Call `render_status` with `{view: "summary"}` to show current state
-→ Determine next action based on workflow state (see Workflow States)
+**If success:**
+→ Display the rendered status
+→ Analyze workflow state and suggest the most appropriate next action (see Workflow States)
+→ If multiple actions are possible, use AskUserQuestion to let user choose
 
 ## Initialization Flow
 
@@ -148,9 +199,38 @@ When determining actions:
 | 50-80% | Suggest action, wait for confirmation |
 | < 50% | Ask clarifying question |
 
+## Help Output
+
+When user runs `/flux help`, display:
+
+```
+Flux - AI-first workflow orchestration
+
+Commands:
+  /flux              Show project status and next action
+  /flux:prd          Create or refine PRDs
+  /flux:breakdown    Break PRD into epics and tasks
+  /flux:implement    Implement tasks with TDD
+  /flux:linear       Connect to Linear
+
+Shortcuts:
+  /flux prd          Same as /flux:prd
+  /flux breakdown    Same as /flux:breakdown
+  /flux implement    Same as /flux:implement
+  /flux status       Show detailed project status
+  /flux version      Show plugin version
+
+Workflow:
+  1. /flux           Initialize project (first time)
+  2. /flux:prd       Create your first PRD
+  3. /flux:breakdown Break PRD into tasks
+  4. /flux:implement Start coding with TDD
+```
+
 ## Guidelines
 
 - Use `AskUserQuestion` tool for all user choices during initialization
 - Be concise - show status and one clear next action
 - Use `render_status` for visual project overview
 - Apply confidence-based autonomy for decisions
+- When user input matches a subcommand pattern, delegate immediately without calling render_status first

package/commands/implement.md

@@ -53,8 +53,7 @@ The orchestrator resolves all refs to tasks, builds a dependency-ordered queue,
 
 ## Pre-checks
 
-1. Call `get_project_context` to ensure Flux is initialized
-2. Parse arguments and resolve to tasks:
+1. Parse arguments and resolve to tasks (if any tool returns `PROJECT_NOT_INITIALIZED` error, tell user: "Run `/flux` first to initialize the project." and exit):
    - No args: Query for next PENDING task with no blockers
    - PRD ref(s): Expand to all epics → all tasks
    - Epic ref(s): Expand to all tasks

package/commands/linear.md

@@ -21,13 +21,14 @@ The `configure_linear` tool supports progressive discovery:
 
 ## Flow
 
-### Step 1: Verify Project
+### Step 1: Verify Project & Fetch Teams
 
-Call `get_project_context`.
+Call `configure_linear` with `{interactive: true}`.
 
-- If `initialized: false` → Tell user to run `/flux` first, then exit.
-- If `adapter.type === "linear"` and config exists → Already configured, show info and exit.
-- Otherwise → Continue to Step 2.
+- If error with `code: "PROJECT_NOT_INITIALIZED"` → Tell user to run `/flux` first, then exit.
+- If error about Linear API key → Show instructions (see Step 2 error handling).
+- If success with `step: "already_configured"` → Already configured, show info and exit.
+- Otherwise → Continue with team selection (response contains teams list).
 
 ### Step 2: Fetch Teams
 

package/commands/prd.md

@@ -20,8 +20,8 @@ Check if arguments were provided:
 
 ### Pre-check
 
-1. Call `get_project_context` to ensure Flux is initialized
-   - If not initialized, tell user: "Run `/flux` first to initialize the project."
+1. Call `query_entities` with `type: "prd"` to verify project is initialized
+   - If error with `code: "PROJECT_NOT_INITIALIZED"`, tell user: "Run `/flux` first to initialize the project." and exit.
 
 2. Call `get_interview` to check for any in-progress interview
    - If exists, ask: "You have an unfinished interview. Resume it or start fresh?"
@@ -96,7 +96,7 @@ Use AskUserQuestion to confirm:
 
 ## After Interview Complete
 
-The `get_project_context` call from Pre-check returns the adapter type. Use this to determine storage behavior.
+The `create_prd` response includes project context. Use it to determine storage behavior, or call `get_entity` on the created PRD to check the adapter type.
 
 ### For Local Adapter (`adapter.type === "local"`):
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cliangdev/flux-plugin",
-  "version": "0.1.0-dev.588ae42",
+  "version": "0.2.0-dev.4f12f3f",
   "description": "Claude Code plugin for AI-first workflow orchestration with MCP server",
   "type": "module",
   "main": "./dist/server/index.js",

package/skills/flux-orchestrator/SKILL.md

@@ -11,11 +11,11 @@ This skill is automatically active when working in a Flux project. It provides c
 ## Available MCP Tools
 
 ### Query Tools
-- `get_project_context` - Check if project initialized, get name/vision/adapter type
 - `get_stats` - Get PRD/epic/task counts by status
 - `get_entity` - Fetch entity by ref with optional includes (criteria, tasks, dependencies)
 - `query_entities` - Search entities by type, status, parent ref
 - `render_status` - Get formatted project status with progress bars
+- `get_version` - Get Flux plugin version
 
 ### Mutation Tools
 - `init_project` - Initialize new .flux/ directory with project.json and database
@@ -107,7 +107,7 @@ Format: `{PREFIX}-{TYPE}{NUMBER}`
 
 ## Best Practices
 
-1. **Check context first** - Call `get_project_context` before actions
+1. **Handle PROJECT_NOT_INITIALIZED** - If any tool returns this error, direct user to run `/flux` to initialize the project
 2. **Use refs, not IDs** - Tools accept `MSA-E1` format
 3. **Use render_status** - For visual project overview
 4. **Validate transitions** - `update_status` enforces valid transitions

package/skills/prd-template/SKILL.md

@@ -219,7 +219,7 @@ erDiagram
 
 ## Workflow
 
-Check adapter type via `get_project_context` to determine storage behavior.
+After creating a PRD, the response includes adapter information. Use this to determine storage behavior.
 
 ### Local Adapter (`adapter.type === "local"`)
 

package/src/server/index.ts

@@ -11,7 +11,6 @@ import {
   createTaskTool,
   deleteEntityTool,
   getEntityTool,
-  getProjectContextTool,
   getStatsTool,
   getVersionTool,
   initProjectTool,
@@ -47,7 +46,6 @@ const tools: ToolDefinition[] = [
   // Query tools
   getEntityTool,
   queryEntitiesTool,
-  getProjectContextTool,
   initProjectTool,
   getStatsTool,
   getVersionTool,

package/src/server/tools/__tests__/mcp-interface.test.ts

@@ -10,7 +10,12 @@ process.env.FLUX_PROJECT_ROOT = TEST_DIR;
 import { z } from "zod";
 import { config } from "../../config.js";
 import { closeDb, initDb } from "../../db/index.js";
-import { createError, registerTools, type ToolDefinition } from "../index.js";
+import {
+  createError,
+  createProjectNotInitializedError,
+  registerTools,
+  type ToolDefinition,
+} from "../index.js";
 
 describe("MCP Interface", () => {
   beforeEach(() => {
@@ -44,6 +49,42 @@ describe("MCP Interface", () => {
     });
   });
 
+  describe("createProjectNotInitializedError", () => {
+    test("creates error with setup instructions", () => {
+      const error = createProjectNotInitializedError("/test/cwd", "/test/root");
+
+      expect(error.error).toBe(true);
+      expect(error.code).toBe("PROJECT_NOT_INITIALIZED");
+      expect(error.message).toContain("/test/cwd");
+      expect(error.message).toContain("/test/root");
+      expect(error.setup.instructions).toBeDefined();
+      expect(error.setup.options).toHaveLength(2);
+    });
+
+    test("includes command option for interactive setup", () => {
+      const error = createProjectNotInitializedError("/cwd", "/root");
+      const commandOption = error.setup.options.find(
+        (o) => o.method === "command",
+      );
+
+      expect(commandOption).toBeDefined();
+      expect(commandOption?.name).toBe("/flux");
+      expect(commandOption?.description).toContain("Interactive");
+    });
+
+    test("includes tool option with required params", () => {
+      const error = createProjectNotInitializedError("/cwd", "/root");
+      const toolOption = error.setup.options.find((o) => o.method === "tool");
+
+      expect(toolOption).toBeDefined();
+      expect(toolOption?.name).toBe("init_project");
+      expect(toolOption?.params).toBeDefined();
+      expect(toolOption?.params?.name).toBeDefined();
+      expect(toolOption?.params?.vision).toBeDefined();
+      expect(toolOption?.params?.adapter).toBeDefined();
+    });
+  });
+
   describe("registerTools", () => {
     test("sets up list tools handler", () => {
       const handlers: Record<string, Function> = {};
@@ -287,7 +328,7 @@ describe("Project Validation", () => {
     }
   });
 
-  test("returns PROJECT_NOT_FOUND for tools requiring project", async () => {
+  test("returns PROJECT_NOT_INITIALIZED with setup instructions for tools requiring project", async () => {
     const handlers: Record<string, Function> = {};
     const mockServer = {
       setRequestHandler: mock((schema: any, handler: Function) => {
@@ -317,7 +358,11 @@ describe("Project Validation", () => {
     expect(result.isError).toBe(true);
     const parsedError = JSON.parse(result.content[0].text);
     expect(parsedError.error).toBe(true);
-    expect(parsedError.code).toBe("PROJECT_NOT_FOUND");
+    expect(parsedError.code).toBe("PROJECT_NOT_INITIALIZED");
+    expect(parsedError.setup).toBeDefined();
+    expect(parsedError.setup.instructions).toBeDefined();
+    expect(parsedError.setup.options).toBeDefined();
+    expect(parsedError.setup.options.length).toBe(2);
   });
 
   test("allows init_project without existing project", async () => {
@@ -353,7 +398,7 @@ describe("Project Validation", () => {
     expect(handlerMock).toHaveBeenCalled();
   });
 
-  test("allows get_project_context without existing project", async () => {
+  test("allows get_version without existing project", async () => {
     const handlers: Record<string, Function> = {};
     const mockServer = {
       setRequestHandler: mock((schema: any, handler: Function) => {
@@ -363,11 +408,11 @@ describe("Project Validation", () => {
       }),
     };
 
-    const handlerMock = mock(async () => ({ initialized: false }));
+    const handlerMock = mock(async () => ({ version: "1.0.0" }));
 
     const testTool: ToolDefinition = {
-      name: "get_project_context",
-      description: "Get project context",
+      name: "get_version",
+      description: "Get version",
       inputSchema: z.object({}),
       handler: handlerMock,
     };
@@ -377,7 +422,7 @@ describe("Project Validation", () => {
     const callHandler = handlers.call;
     const result = await callHandler({
       params: {
-        name: "get_project_context",
+        name: "get_version",
         arguments: {},
       },
     });
@@ -385,4 +430,49 @@ describe("Project Validation", () => {
     expect(result.isError).toBeUndefined();
     expect(handlerMock).toHaveBeenCalled();
   });
+
+  test("setup options have correct structure", async () => {
+    const handlers: Record<string, Function> = {};
+    const mockServer = {
+      setRequestHandler: mock((schema: any, handler: Function) => {
+        if (schema.shape?.method?.value === "tools/call") {
+          handlers.call = handler;
+        }
+      }),
+    };
+
+    const testTool: ToolDefinition = {
+      name: "query_entities",
+      description: "Query entities",
+      inputSchema: z.object({ type: z.string() }),
+      handler: async () => ({ items: [] }),
+    };
+
+    registerTools(mockServer as any, [testTool]);
+
+    const callHandler = handlers.call;
+    const result = await callHandler({
+      params: {
+        name: "query_entities",
+        arguments: { type: "prd" },
+      },
+    });
+
+    expect(result.isError).toBe(true);
+    const parsedError = JSON.parse(result.content[0].text);
+
+    const commandOption = parsedError.setup.options.find(
+      (o: any) => o.method === "command",
+    );
+    expect(commandOption.name).toBe("/flux");
+    expect(commandOption.description).toBeTruthy();
+
+    const toolOption = parsedError.setup.options.find(
+      (o: any) => o.method === "tool",
+    );
+    expect(toolOption.name).toBe("init_project");
+    expect(toolOption.params.name).toBeTruthy();
+    expect(toolOption.params.vision).toBeTruthy();
+    expect(toolOption.params.adapter).toBeTruthy();
+  });
 });

package/src/server/tools/__tests__/query.test.ts

@@ -16,7 +16,6 @@ import { createPrdTool } from "../create-prd.js";
 import { createTaskTool } from "../create-task.js";
 import { addDependencyTool } from "../dependencies.js";
 import { getEntityTool } from "../get-entity.js";
-import { getProjectContextTool } from "../get-project-context.js";
 import { getStatsTool } from "../get-stats.js";
 import { initProjectTool } from "../init-project.js";
 import { queryEntitiesTool } from "../query-entities.js";
@@ -242,24 +241,6 @@ describe("Query MCP Tools", () => {
     });
   });
 
-  describe("get_project_context", () => {
-    test("returns project context when initialized", async () => {
-      const result = (await getProjectContextTool.handler({})) as any;
-
-      expect(result.initialized).toBe(true);
-      expect(result.name).toBe("test-project");
-      expect(result.ref_prefix).toBe("TEST");
-    });
-
-    test("returns initialized false when no project", async () => {
-      // Remove the project.json
-      rmSync(join(FLUX_DIR, "project.json"));
-
-      const result = (await getProjectContextTool.handler({})) as any;
-      expect(result.initialized).toBe(false);
-    });
-  });
-
   describe("get_stats", () => {
     test("returns zeroes for empty project", async () => {
       const result = (await getStatsTool.handler({})) as any;

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/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,
-};