@cliangdev/flux-plugin 0.4.0-dev.0892a21 → 0.4.0-dev.236e9f1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cliangdev/flux-plugin",
-  "version": "0.4.0-dev.0892a21",
+  "version": "0.4.0-dev.236e9f1",
   "description": "Claude Code plugin for AI-first workflow orchestration with MCP server",
   "type": "module",
   "main": "./dist/server/index.js",

package/src/server/adapters/github/__tests__/prd-crud.test.ts

@@ -223,7 +223,14 @@ describe("prd status mappers", () => {
     expect(prdStatusToLabel("ARCHIVED")).toBeNull();
   });
 
-  test("labelToPrdStatus detects ARCHIVED from closed state", async () => {
+  test("labelToPrdStatus detects COMPLETED from closed state with completed label", async () => {
+    const { labelToPrdStatus } = await import("../mappers/prd.js");
+    expect(labelToPrdStatus(["flux:prd", "status:completed"], true)).toBe(
+      "COMPLETED",
+    );
+  });
+
+  test("labelToPrdStatus detects ARCHIVED from closed state without completed label", async () => {
     const { labelToPrdStatus } = await import("../mappers/prd.js");
     expect(labelToPrdStatus(["flux:prd", "status:draft"], true)).toBe(
       "ARCHIVED",
@@ -292,7 +299,7 @@ describe("GitHubAdapter PRD CRUD", () => {
   afterEach(() => {});
 
   describe("createPrd", () => {
-    test("returns Prd with DRAFT status and correct folderPath", async () => {
+    test("returns Prd with DRAFT status and no folderPath", async () => {
       const issue = makeIssue({
         number: 42,
         title: "My New PRD",
@@ -315,7 +322,7 @@ describe("GitHubAdapter PRD CRUD", () => {
 
       expect(prd.status).toBe("DRAFT");
       expect(prd.ref).toBe("FP-P42");
-      expect(prd.folderPath).toBe("prds/fp-p42/");
+      expect(prd.folderPath).toBeUndefined();
       expect(prd.title).toBe("My New PRD");
     });
 
@@ -529,7 +536,7 @@ describe("GitHubAdapter PRD CRUD", () => {
       expect(prd?.title).toBe("My PRD");
     });
 
-    test("returns Prd with correct folderPath derived from ref", async () => {
+    test("returns Prd without folderPath (GitHub adapter stores content in issue body)", async () => {
       const issue = makeIssue({
         number: 9,
         title: "Folder PRD",
@@ -551,7 +558,7 @@ describe("GitHubAdapter PRD CRUD", () => {
       const adapter = makeAdapter();
       const prd = await adapter.getPrd("FP-P9");
 
-      expect(prd?.folderPath).toBe("prds/fp-p9/");
+      expect(prd?.folderPath).toBeUndefined();
     });
   });
 

package/src/server/adapters/github/adapter.ts

@@ -50,6 +50,17 @@ import {
 } from "./mappers/index.js";
 import { GITHUB_LABELS, type GitHubConfig } from "./types.js";
 
+const STATUS_TO_BOARD_COLUMN: Record<string, string> = {
+  DRAFT: "Draft",
+  PENDING: "Draft",
+  PENDING_REVIEW: "Pending Review",
+  REVIEWED: "Reviewed",
+  APPROVED: "Approved",
+  BREAKDOWN_READY: "Breakdown Ready",
+  IN_PROGRESS: "In Progress",
+  COMPLETED: "Completed",
+};
+
 interface GitHubIssue {
   number: number;
   id: number;
@@ -72,7 +83,6 @@ function issueToPrd(issue: GitHubIssue, config: GitHubConfig): Prd {
   const meta = decodeMeta(issue.body || "");
   const labels = issue.labels.map((l) => l.name);
   const ref = meta?.ref ?? `${config.refPrefix}-P${issue.number}`;
-  const refSlug = ref.toLowerCase().replace(":", "-");
   const tag = labelToTag(labels) ?? meta?.tag;
   return {
     id: String(issue.number),
@@ -82,7 +92,6 @@ function issueToPrd(issue: GitHubIssue, config: GitHubConfig): Prd {
     description: extractDescription(issue.body || ""),
     status: labelToPrdStatus(labels, issue.state === "closed"),
     tag,
-    folderPath: `prds/${refSlug}/`,
     createdAt: issue.created_at,
     updatedAt: issue.updated_at,
   };
@@ -149,8 +158,8 @@ export class GitHubAdapter implements BackendAdapter {
     return null;
   }
 
-  private async addToProjectsBoard(issueNodeId: string): Promise<void> {
-    await this.client.graphql(
+  private async addToProjectsBoard(issueNodeId: string): Promise<string> {
+    const result = await this.client.graphql(
       `
       mutation AddToProject($projectId: ID!, $contentId: ID!) {
         addProjectV2ItemById(input: { projectId: $projectId, contentId: $contentId }) {
@@ -160,6 +169,79 @@ export class GitHubAdapter implements BackendAdapter {
     `,
       { projectId: this.config.projectId, contentId: issueNodeId },
     );
+    return (result as { addProjectV2ItemById: { item: { id: string } } })
+      .addProjectV2ItemById.item.id;
+  }
+
+  private async setProjectBoardStatus(
+    itemId: string,
+    status: string,
+  ): Promise<void> {
+    const sf = this.config.statusField;
+    if (!sf) return;
+
+    const columnName = STATUS_TO_BOARD_COLUMN[status];
+    if (!columnName) return;
+
+    const optionId = sf.optionIds[columnName];
+    if (!optionId) return;
+
+    await this.client.graphql(
+      `
+      mutation SetStatus($projectId: ID!, $itemId: ID!, $fieldId: ID!, $optionId: String!) {
+        updateProjectV2ItemFieldValue(input: {
+          projectId: $projectId
+          itemId: $itemId
+          fieldId: $fieldId
+          value: { singleSelectOptionId: $optionId }
+        }) {
+          projectV2Item { id }
+        }
+      }
+    `,
+      {
+        projectId: this.config.projectId,
+        itemId,
+        fieldId: sf.fieldId,
+        optionId,
+      },
+    );
+  }
+
+  private async findProjectItemId(issueNodeId: string): Promise<string | null> {
+    const result = await this.client.graphql(
+      `
+      query FindProjectItem($projectId: ID!, $contentId: ID!) {
+        node(id: $projectId) {
+          ... on ProjectV2 {
+            items(first: 100) {
+              nodes {
+                id
+                content { ... on Issue { id } ... on PullRequest { id } }
+              }
+            }
+          }
+        }
+      }
+    `,
+      { projectId: this.config.projectId, contentId: issueNodeId },
+    );
+
+    const items = (
+      result as {
+        node: {
+          items: {
+            nodes: Array<{
+              id: string;
+              content: { id: string } | null;
+            }>;
+          };
+        };
+      }
+    ).node.items.nodes;
+
+    const match = items.find((item) => item.content?.id === issueNodeId);
+    return match?.id ?? null;
   }
 
   async createPrd(input: CreatePrdInput): Promise<Prd> {
@@ -204,7 +286,8 @@ export class GitHubAdapter implements BackendAdapter {
       body: finalBody,
     });
 
-    await this.addToProjectsBoard(createdIssue.node_id);
+    const projectItemId = await this.addToProjectsBoard(createdIssue.node_id);
+    await this.setProjectBoardStatus(projectItemId, "DRAFT");
     await this.addToIndex(ref, issueNumber);
 
     const getResponse = await this.client.rest.issues.get({
@@ -279,7 +362,7 @@ export class GitHubAdapter implements BackendAdapter {
       updateParams.title = input.title;
     }
 
-    if (newStatus === "ARCHIVED") {
+    if (newStatus === "COMPLETED" || newStatus === "ARCHIVED") {
       updateParams.state = "closed";
     }
 
@@ -287,6 +370,13 @@ export class GitHubAdapter implements BackendAdapter {
       updateParams as Parameters<typeof this.client.rest.issues.update>[0],
     );
 
+    if (input.status && this.config.statusField) {
+      const itemId = await this.findProjectItemId(existingIssue.node_id);
+      if (itemId) {
+        await this.setProjectBoardStatus(itemId, newStatus);
+      }
+    }
+
     return issueToPrd(updateResponse.data as GitHubIssue, this.config);
   }
 
@@ -524,7 +614,8 @@ export class GitHubAdapter implements BackendAdapter {
       // sub-issue linking is cosmetic for GitHub UI; hierarchy is stored in flux-meta
     }
 
-    await this.addToProjectsBoard(createdIssue.node_id);
+    const epicItemId = await this.addToProjectsBoard(createdIssue.node_id);
+    await this.setProjectBoardStatus(epicItemId, "PENDING");
     await this.addToIndex(ref, issueNumber);
 
     const getResponse = await this.client.rest.issues.get({
@@ -598,6 +689,13 @@ export class GitHubAdapter implements BackendAdapter {
       updateParams as Parameters<typeof this.client.rest.issues.update>[0],
     );
 
+    if (input.status && this.config.statusField) {
+      const itemId = await this.findProjectItemId(existingIssue.node_id);
+      if (itemId) {
+        await this.setProjectBoardStatus(itemId, newStatus);
+      }
+    }
+
     return this.issueToEpic(updateResponse.data as GitHubIssue);
   }
 
@@ -817,7 +915,8 @@ export class GitHubAdapter implements BackendAdapter {
       // sub-issue linking is cosmetic for GitHub UI; hierarchy is in flux-meta
     }
 
-    await this.addToProjectsBoard(createdIssue.node_id);
+    const taskItemId = await this.addToProjectsBoard(createdIssue.node_id);
+    await this.setProjectBoardStatus(taskItemId, "PENDING");
     await this.addToIndex(ref, issueNumber);
 
     const getResponse = await this.client.rest.issues.get({
@@ -902,6 +1001,13 @@ export class GitHubAdapter implements BackendAdapter {
       updateParams as Parameters<typeof this.client.rest.issues.update>[0],
     );
 
+    if (input.status && this.config.statusField) {
+      const itemId = await this.findProjectItemId(existingIssue.node_id);
+      if (itemId) {
+        await this.setProjectBoardStatus(itemId, newStatus);
+      }
+    }
+
     return this.issueToTask(updateResponse.data as GitHubIssue);
   }
 

package/src/server/adapters/github/mappers/prd.ts

@@ -23,7 +23,10 @@ export function labelToPrdStatus(
   labels: string[],
   isClosed: boolean,
 ): PrdStatus {
-  if (isClosed) return "ARCHIVED";
+  if (isClosed) {
+    if (labels.includes(GITHUB_LABELS.STATUS_COMPLETED)) return "COMPLETED";
+    return "ARCHIVED";
+  }
 
   if (labels.includes(GITHUB_LABELS.STATUS_COMPLETED)) return "COMPLETED";
   if (labels.includes(GITHUB_LABELS.STATUS_BREAKDOWN_READY))

package/src/server/adapters/github/types.ts

@@ -1,9 +1,15 @@
+export interface ProjectStatusField {
+  fieldId: string;
+  optionIds: Record<string, string>;
+}
+
 export interface GitHubConfig {
   token: string;
   owner: string;
   repo: string;
   projectId: string;
   refPrefix: string;
+  statusField?: ProjectStatusField;
 }
 
 export const GITHUB_LABELS = {

package/src/server/index.ts

@@ -12,6 +12,7 @@ import {
   createTaskTool,
   deleteEntityTool,
   getEntityTool,
+  getProjectContextTool,
   getStatsTool,
   getVersionTool,
   initProjectTool,
@@ -48,6 +49,7 @@ const tools: ToolDefinition[] = [
   getEntityTool,
   queryEntitiesTool,
   initProjectTool,
+  getProjectContextTool,
   getStatsTool,
   getVersionTool,
   // Configuration tools

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

@@ -0,0 +1,81 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const TEST_DIR = `/tmp/flux-test-project-context-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+const FLUX_DIR = join(TEST_DIR, ".flux");
+process.env.FLUX_PROJECT_ROOT = TEST_DIR;
+
+import { config } from "../../config.js";
+import { getProjectContextTool } from "../get-project-context.js";
+
+describe("get_project_context", () => {
+  beforeEach(() => {
+    config.clearCache();
+    process.env.FLUX_PROJECT_ROOT = TEST_DIR;
+    mkdirSync(FLUX_DIR, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(TEST_DIR, { recursive: true, force: true });
+  });
+
+  test("returns local adapter when no adapter configured", async () => {
+    writeFileSync(
+      join(FLUX_DIR, "project.json"),
+      JSON.stringify({ name: "test-project", vision: "A test project" }),
+    );
+
+    const result = (await getProjectContextTool.handler({})) as any;
+
+    expect(result.name).toBe("test-project");
+    expect(result.vision).toBe("A test project");
+    expect(result.adapter.type).toBe("local");
+  });
+
+  test("returns github adapter type when configured", async () => {
+    writeFileSync(
+      join(FLUX_DIR, "project.json"),
+      JSON.stringify({
+        name: "gh-project",
+        vision: "GitHub project",
+        refPrefix: "GH",
+        adapter: { type: "github" },
+      }),
+    );
+
+    const result = (await getProjectContextTool.handler({})) as any;
+
+    expect(result.name).toBe("gh-project");
+    expect(result.vision).toBe("GitHub project");
+    expect(result.ref_prefix).toBe("GH");
+    expect(result.adapter.type).toBe("github");
+  });
+
+  test("returns linear adapter type when configured", async () => {
+    writeFileSync(
+      join(FLUX_DIR, "project.json"),
+      JSON.stringify({
+        name: "linear-project",
+        adapter: { type: "linear" },
+      }),
+    );
+
+    const result = (await getProjectContextTool.handler({})) as any;
+
+    expect(result.name).toBe("linear-project");
+    expect(result.adapter.type).toBe("linear");
+  });
+
+  test("has correct tool definition", () => {
+    expect(getProjectContextTool.name).toBe("get_project_context");
+    expect(getProjectContextTool.description).toContain("adapter");
+    expect(getProjectContextTool.inputSchema).toBeDefined();
+    expect(getProjectContextTool.handler).toBeDefined();
+  });
+
+  test("throws when project.json does not exist", async () => {
+    // No project.json written
+    expect(getProjectContextTool.handler({})).rejects.toThrow();
+  });
+});

package/src/server/tools/__tests__/z-configure-github.test.ts

@@ -126,6 +126,45 @@ mock.module("@octokit/graphql", () => ({
               linkProjectV2ToRepository: { repository: { id: "REPO_NODE_ID" } },
             };
           }
+          if (query.includes("GetProjectFields")) {
+            return {
+              node: {
+                fields: {
+                  nodes: [
+                    {
+                      id: "PVTSSF_STATUS",
+                      name: "Status",
+                      options: [
+                        { id: "OPT_TODO", name: "Todo" },
+                        { id: "OPT_INPROGRESS", name: "In Progress" },
+                        { id: "OPT_DONE", name: "Done" },
+                      ],
+                    },
+                  ],
+                },
+              },
+            };
+          }
+          if (
+            query.includes("UpdateStatusOptions") ||
+            query.includes("updateProjectV2Field")
+          ) {
+            return {
+              updateProjectV2Field: {
+                projectV2Field: {
+                  options: [
+                    { id: "OPT_DRAFT", name: "Draft" },
+                    { id: "OPT_PENDING_REVIEW", name: "Pending Review" },
+                    { id: "OPT_REVIEWED", name: "Reviewed" },
+                    { id: "OPT_APPROVED", name: "Approved" },
+                    { id: "OPT_BREAKDOWN_READY", name: "Breakdown Ready" },
+                    { id: "OPT_IN_PROGRESS", name: "In Progress" },
+                    { id: "OPT_COMPLETED", name: "Completed" },
+                  ],
+                },
+              },
+            };
+          }
           throw new Error(`Unhandled GraphQL query: ${query}`);
         };
       },

package/src/server/tools/configure-github.ts

@@ -17,11 +17,17 @@ const inputSchema = z.object({
 
 type ConfigureMode = "setup" | "join" | "update";
 
+interface StatusFieldConfig {
+  fieldId: string;
+  optionIds: Record<string, string>;
+}
+
 interface SharedConfig {
   owner: string;
   repo: string;
   projectId: string;
   refPrefix: string;
+  statusField?: StatusFieldConfig;
 }
 
 interface ConfigureResult {
@@ -214,6 +220,98 @@ async function createProjectsBoard(
   return project;
 }
 
+const BOARD_STATUS_OPTIONS: Array<{
+  name: string;
+  color: string;
+  description: string;
+}> = [
+  { name: "Draft", color: "GRAY", description: "" },
+  { name: "Pending Review", color: "YELLOW", description: "" },
+  { name: "Reviewed", color: "PURPLE", description: "" },
+  { name: "Approved", color: "GREEN", description: "" },
+  { name: "Breakdown Ready", color: "BLUE", description: "" },
+  { name: "In Progress", color: "ORANGE", description: "" },
+  { name: "Completed", color: "GREEN", description: "" },
+];
+
+async function configureStatusField(
+  gql: (
+    query: string,
+    vars: Record<string, unknown>,
+  ) => Promise<Record<string, Record<string, unknown>>>,
+  projectId: string,
+): Promise<StatusFieldConfig | undefined> {
+  const result = await gql(
+    `query GetProjectFields($projectId: ID!) {
+      node(id: $projectId) {
+        ... on ProjectV2 {
+          fields(first: 20) {
+            nodes {
+              ... on ProjectV2SingleSelectField {
+                id
+                name
+                options { id name }
+              }
+            }
+          }
+        }
+      }
+    }`,
+    { projectId },
+  );
+
+  const fields = (
+    result.node as {
+      fields: {
+        nodes: Array<{
+          id?: string;
+          name?: string;
+          options?: Array<{ id: string; name: string }>;
+        }>;
+      };
+    }
+  ).fields.nodes;
+
+  const statusField = fields.find(
+    (f) => f.name === "Status" && f.options && f.id,
+  );
+  if (!statusField?.id) return undefined;
+
+  const updateResult = await gql(
+    `mutation UpdateStatusOptions($fieldId: ID!, $options: [ProjectV2SingleSelectFieldOptionInput!]!) {
+      updateProjectV2Field(input: {
+        fieldId: $fieldId
+        singleSelectOptions: $options
+      }) {
+        projectV2Field {
+          ... on ProjectV2SingleSelectField {
+            options { id name }
+          }
+        }
+      }
+    }`,
+    {
+      fieldId: statusField.id,
+      options: BOARD_STATUS_OPTIONS,
+    },
+  );
+
+  const updatedOptions = (
+    updateResult.updateProjectV2Field as {
+      projectV2Field: {
+        options: Array<{ id: string; name: string }>;
+      };
+    }
+  ).projectV2Field.options;
+
+  const optionIds: Record<string, string> = {};
+  for (const opt of updatedOptions) {
+    optionIds[opt.name] = opt.id;
+  }
+
+  return { fieldId: statusField.id, optionIds };
+}
+
 async function commitSharedConfig(
   octokit: Octokit,
   owner: string,
@@ -238,6 +336,7 @@ function writeProjectJson(params: {
   repo: string;
   projectId: string;
   refPrefix: string;
+  statusField?: StatusFieldConfig;
 }): void {
   const projectJsonPath = config.projectJsonPath;
   const existing = existsSync(projectJsonPath)
@@ -252,6 +351,7 @@ function writeProjectJson(params: {
       repo: params.repo,
       projectId: params.projectId,
       refPrefix: params.refPrefix,
+      ...(params.statusField ? { statusField: params.statusField } : {}),
     },
   };
 
@@ -290,11 +390,14 @@ async function runSetup(params: {
     params.repo,
   );
 
+  const statusField = await configureStatusField(params.gql, project.id);
+
   const sharedConfig: SharedConfig = {
     owner: params.owner,
     repo: params.repo,
     projectId: project.id,
     refPrefix: params.refPrefix,
+    ...(statusField ? { statusField } : {}),
   };
 
   await commitSharedConfig(
@@ -310,6 +413,7 @@ async function runSetup(params: {
     repo: params.repo,
     projectId: project.id,
     refPrefix: params.refPrefix,
+    statusField,
   });
 
   return {
@@ -332,6 +436,7 @@ async function runJoin(params: {
     repo: params.remoteConfig.repo,
     projectId: params.remoteConfig.projectId,
     refPrefix: params.remoteConfig.refPrefix,
+    statusField: params.remoteConfig.statusField,
   });
 
   const repoUrl = `https://github.com/${params.remoteConfig.owner}/${params.remoteConfig.repo}`;
@@ -348,10 +453,26 @@ async function runUpdate(params: {
   token: string;
   owner: string;
   repo: string;
+  gql: (
+    query: string,
+    vars: Record<string, unknown>,
+  ) => Promise<Record<string, Record<string, unknown>>>;
 }): Promise<ConfigureResult> {
   const projectJsonPath = config.projectJsonPath;
   const existing = JSON.parse(readFileSync(projectJsonPath, "utf-8"));
   existing.adapter.config.token = params.token;
+
+  const adapterConfig = existing.adapter?.config;
+  if (adapterConfig?.projectId && !adapterConfig.statusField) {
+    const statusField = await configureStatusField(
+      params.gql,
+      adapterConfig.projectId,
+    );
+    if (statusField) {
+      adapterConfig.statusField = statusField;
+    }
+  }
+
   writeFileSync(projectJsonPath, JSON.stringify(existing, null, 2));
 
   const repoUrl = `https://github.com/${params.owner}/${params.repo}`;
@@ -399,6 +520,7 @@ async function handler(input: unknown) {
       token,
       owner: parsed.owner,
       repo: parsed.repo,
+      gql: gqlWithAuth,
     });
   } else if (mode === "join" && remoteConfig) {
     result = await runJoin({

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

@@ -0,0 +1,28 @@
+import { 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 content = readFileSync(config.projectJsonPath, "utf-8");
+  const project = JSON.parse(content);
+
+  return {
+    name: project.name ?? null,
+    vision: project.vision ?? null,
+    ref_prefix: project.refPrefix ?? null,
+    adapter: {
+      type: project.adapter?.type ?? "local",
+    },
+  };
+}
+
+export const getProjectContextTool: ToolDefinition = {
+  name: "get_project_context",
+  description:
+    "Get project context including adapter type, project name, vision, and ref prefix. No parameters required. Returns {name, vision, ref_prefix, adapter: {type: 'local' | 'github' | 'linear'}}. Use this to detect which adapter is configured before performing adapter-specific operations.",
+  inputSchema,
+  handler,
+};

package/src/server/tools/index.ts

@@ -150,6 +150,7 @@ 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";